{"id":13180,"library":"fbt","title":"FBT Internationalization Framework Runtime","description":"FBT (Facebook's Internationalization Framework) provides a JavaScript runtime for building grammatically correct, translatable user interfaces. Currently at version 1.0.2, this package handles the client-side execution of FBT-transformed strings. It doesn't provide translations itself but offers the APIs to manage them. FBT differentiates itself by enabling translatable text to reside directly within JSX, enhancing searchability and developer experience. It robustly supports complex localization features like plural variations, gender-based pronouns, and enumerations natively. The framework leverages Babel plugins during the build process to extract strings and generate optimized translation payloads, which are then utilized by this runtime package.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/fbt","tags":["javascript","facebook","fbt","globalization","i18n","internationalization","l10n","localization","react"],"install":[{"cmd":"npm install fbt","lang":"bash","label":"npm"},{"cmd":"yarn add fbt","lang":"bash","label":"yarn"},{"cmd":"pnpm add fbt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required Babel plugin for compile-time FBT transformations and string extraction.","package":"babel-plugin-fbt","optional":false},{"reason":"Secondary Babel plugin that transforms raw FBT payloads for efficient runtime consumption.","package":"babel-plugin-fbt-runtime","optional":false},{"reason":"Peer dependency, as FBT is designed for tight integration with React applications.","package":"react","optional":false}],"imports":[{"note":"The `fbt` object is typically imported as a default, providing both the functional API (fbt(...)) and the JSX component (<fbt>). CommonJS `require` is not the recommended or natively supported way for modern FBT usage, especially in ESM-first projects. The `init` function is a named export from the primary module.","wrong":"const fbt = require('fbt');","symbol":"fbt","correct":"import fbt, { init } from 'fbt';"},{"note":"`IntlViewerContext` is a named export, typically used in React contexts to manage and provide locale information across the component tree. While `fbt` can be imported alongside it, it's distinct.","wrong":"import fbt, { IntlViewerContext } from 'fbt';","symbol":"IntlViewerContext","correct":"import { IntlViewerContext } from 'fbt';"},{"note":"The `<fbt>` JSX component is available through the default import of the `fbt` module. Attempting to destructure it as a named export like `{ fbt }` will lead to runtime errors for the JSX element usage. It also requires the `babel-plugin-fbt` to transform the JSX syntax.","wrong":"import { fbt } from 'fbt';\n// ... in a React component\n<fbt desc=\"A user greeting\">Hello World!</fbt>","symbol":"<fbt>","correct":"import fbt from 'fbt';\n// ... in a React component\n<fbt desc=\"A user greeting\">Hello World!</fbt>"}],"quickstart":{"code":"import React from 'react';\nimport fbt, { init, IntlViewerContext } from 'fbt';\n\n// In a real application, this would come from your build-time generated translations\nconst translations = {\n  // Example structure (hashes generated by fbt-collect script)\n  'ni7kanCF2RfGZAS9mDOToQ==': 'Hello, World!',\n  '1j2k3l4m5n6o7p==': 'You have {number} unread messages.',\n  '8q9r0s1t2u3v4w==': '{name} joined the chat.',\n};\n\n// Initialize FBT with the current locale and translation data\n// This should ideally happen once at the root of your application\nconst currentLocale = 'en_US';\ninit({\n  translations: { [currentLocale]: translations },\n  locale: currentLocale,\n});\n\nfunction App() {\n  const userName = 'Alice';\n  const messageCount = 5;\n\n  return (\n    <div>\n      {/* Using the JSX API */}\n      <h1>\n        <fbt desc=\"A general welcome message\">Welcome to FBT Demo!</fbt>\n      </h1>\n\n      {/* Using the functional API */}\n      <p>\n        {fbt(\n          'You have ' + fbt.param('number', messageCount) + ' unread messages.',\n          'User unread message count',\n        )}\n      </p>\n\n      {/* Combining JSX and parameters */}\n      <p>\n        <fbt desc=\"User joined message\">\n          <fbt:param name=\"name\">{userName}</fbt:param> joined the chat.\n        </fbt>\n      </p>\n\n      <p>Current Locale: {IntlViewerContext.get.</p>\n    </div>\n  );\n}\n\nexport default App;","lang":"typescript","description":"This quickstart demonstrates basic FBT usage within a React component, showing both JSX and functional API for internationalized strings, along with essential FBT runtime initialization and locale display."},"warnings":[{"fix":"Ensure your build pipeline is correctly configured with `babel-plugin-fbt` and `babel-plugin-fbt-runtime`. Implement the FBT-specific workflow scripts (`fbt-manifest`, `fbt-collect`, `fbt-translate`) to generate translation files before runtime.","message":"FBT requires a build-time step involving Babel plugins (`babel-plugin-fbt`, `babel-plugin-fbt-runtime`) to extract translatable strings and generate translation payloads. It is not a runtime-only solution like some other i18n libraries.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Develop a translation workflow to generate `.source_strings.json` using `fbt-collect`, have human translators populate these files for each locale, and then use `fbt-translate` to create the final runtime translation payloads.","message":"FBT itself does not provide translations; it manages the process of marking strings for translation and using provided translations. You are responsible for creating or acquiring the actual translated text for each locale.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you have the necessary `@types/fbt` package installed (if available) and your `tsconfig.json` includes appropriate settings for JSX (`jsxFactory`, `jsxFragmentFactory`) and `esModuleInterop`. Manual type declaration augmentation might be necessary if `@types/fbt` is insufficient.","message":"When using FBT with TypeScript, you may encounter type errors if the global JSX types are not correctly augmented to recognize the `<fbt>` element or if the `fbt` module's types are not properly configured/installed.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import fbt from 'fbt';` to ensure the JSX transform correctly identifies the FBT component.","cause":"Attempting to use `<fbt>` as a JSX component when `fbt` was imported as a named export (`import { fbt } from 'fbt';`) instead of a default import.","error":"Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object."},{"fix":"Call `fbt.init({ translations: { ... }, locale: '...' })` once at the very beginning of your application's lifecycle, typically in your main entry file (e.g., `index.js` or `App.js`), before any components using FBT are rendered.","cause":"The FBT runtime was used (e.g., an `<fbt>` component rendered or `fbt()` function called) before the `init` function was invoked with translation data and the current locale.","error":"fbt: `fbt.init()` must be called before using fbt."},{"fix":"Ensure `fbt.init()` is called globally at the application entry point with valid translation data and locale, which sets up the `IntlViewerContext`.","cause":"This often happens when `IntlViewerContext.get` is accessed, but `fbt.init` has not been called, meaning the `IntlViewerContext` hasn't been properly initialized.","error":"TypeError: Cannot read properties of undefined (reading 'get')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}