fbt

library0.1.0jsnpmunverified

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.

serialization

npm install fbt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FBT

fbt

serializationjavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fbt

✓ import fbt, { init } from 'fbt';

✗ const fbt = require('fbt');

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.

IntlViewerContext

✓ import { IntlViewerContext } from 'fbt';

✗ import fbt, { IntlViewerContext } from 'fbt';

`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.

<fbt>

✓ import fbt from 'fbt'; // ... in a React component <fbt desc="A user greeting">Hello World!</fbt>

✗ import { fbt } from 'fbt'; // ... in a React component <fbt desc="A user greeting">Hello World!</fbt>

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.

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.

import React from 'react'; import fbt, { init, IntlViewerContext } from 'fbt'; // In a real application, this would come from your build-time generated translations const translations = { // Example structure (hashes generated by fbt-collect script) 'ni7kanCF2RfGZAS9mDOToQ==': 'Hello, World!', '1j2k3l4m5n6o7p==': 'You have {number} unread messages.', '8q9r0s1t2u3v4w==': '{name} joined the chat.', }; // Initialize FBT with the current locale and translation data // This should ideally happen once at the root of your application const currentLocale = 'en_US'; init({ translations: { [currentLocale]: translations }, locale: currentLocale, }); function App() { const userName = 'Alice'; const messageCount = 5; return ( <div> {/* Using the JSX API */} <h1> <fbt desc="A general welcome message">Welcome to FBT Demo!</fbt> </h1> {/* Using the functional API */} <p> {fbt( 'You have ' + fbt.param('number', messageCount) + ' unread messages.', 'User unread message count', )} </p> {/* Combining JSX and parameters */} <p> <fbt desc="User joined message"> <fbt:param name="name">{userName}</fbt:param> joined the chat. </fbt> </p> <p>Current Locale: {IntlViewerContext.get.</p> </div> ); } export default App;

Debug

Known issues

gotchaFBT 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.

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.

affects: >=1.0.0

gotchaFBT 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.

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.

affects: >=1.0.0

gotchaWhen 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

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.

fix

Change your import statement to `import fbt from 'fbt';` to ensure the JSX transform correctly identifies the FBT component.

fbt: `fbt.init()` must be called before using fbt.

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.

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.

TypeError: Cannot read properties of undefined (reading 'get')

This often happens when `IntlViewerContext.get` is accessed, but `fbt.init` has not been called, meaning the `IntlViewerContext` hasn't been properly initialized.

fix

Ensure `fbt.init()` is called globally at the application entry point with valid translation data and locale, which sets up the `IntlViewerContext`.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

babel-plugin-fbtrequiredRequired Babel plugin for compile-time FBT transformations and string extraction.

babel-plugin-fbt-runtimerequiredSecondary Babel plugin that transforms raw FBT payloads for efficient runtime consumption.

reactrequiredPeer dependency, as FBT is designed for tight integration with React applications.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/facebook/fbt ↗

packagehttps://www.npmjs.com/package/fbt ↗

homepagehttps://facebook.github.io/fbt/ ↗