Try the Demo

Check out our Github repository and run the Webpack demo app. See "Building and starting the demo app"

Integrating into your app

NPM module dependencies

The required NPM modules to add to your dependencies in your app are:

• fbt - The fbt runtime module
• babel-plugin-fbt - The primary Babel transform
• babel-plugin-fbt-runtime - The secondary Babel transform
  • Transforms the raw payloads within fbt._(...) so they can be used at runtime (by fbt._)
  • NOTE: This plugin should get merged into babel-plugin-fbt
• @fbtjs/default-collection-transform
  • Only required if if you elect not to pass a custom --transform nor --custom-collector in the collection script

If you're unfamiliar with Babel, you can read through their documentation here

Babel Plugin ordering (Caveat)

There is a plugin ordering gotcha to be aware of if you use other Babel plugins. FBT expects to be the first plugin to visit its relevant <fbt> and fbt(...) nodes See this Github issue tracking this

You'll hit issues if another transforms beats the babel-plugin-fbt to the Babel AST, node and transforms it such that the plugin doesn't "recognize" as an fbt node anymore. This is most commonly on JSX nodes. To work around this you can use Babel's passPerPreset option, and ensure babel-plugin-fbt is in an earlier preset bundle:

babel.transformSync(source, {

passPerPreset: true,

{presets: [

{plugins: [‘babel-plugin-fbt’, ‘babel-plugin-fbt-runtime'...]}

{plugins: [‘babel-plugin-jsx-foo’, ...]} //

]},

... // your other options

})

Webpack Example

You'll need to add the fbt babel transforms in a manner similar to our demo-app. See our demo-app's Webpack config

Build-time / offline processes

Collection

There are scripts bundled into the babel-plugin-fbt package that are designed for collecting source text (and associated metadata) from your application's source. These are:

• fbt-manifest - Scans provided filesystem paths and generates a manifest of the enumeration modules
  • NOTE: Enum modules must end in $FbtEnum.(js|jsx|ts|tsx) (i.e. Foo$FbtEnum.js)
• fbt-collectFbt - Given source input, extract any source text and print them to STDOUT as JSON
  • @fbtjs/default-collection-transform - As mentioned, this optional package provides a default transform for collection

Translation

• fbt-translate - Creates translation payloads for runtime
  • Takes extracted source text (from collectFbt) and translations provided in JSON format to produce these payloads

How to use these scripts

You can see how the demo-app calls into these scripts here.

The demo app runs all these in another script, here

Runtime

The fbt runtime is what resolves the translation payload table generated during the translation phase into a singular result base on all the input provided at runtime.

Initialization

The fbt runtime requires that you initialize with your relevant translations via the init() function. You can see an example of this in the demo-app.

Changing of translation locale on the fly

Let's assume you've split your translation payloads per locale using the --output-dir option of the translate script. In this example, your app was initialized with the es_ES translation payload and, upon user request, you need to load fr_FR translations and show these in the UI. (We'll assume that your app already has access to the new translation payload)

In order to change of translation locale on the fly, you'll need to do all the items below:

1. Update the translation payload by calling FbtTranslations.registerTranslations(newTranslationPayload). The translation payload object used there should have the same structure as what was passed to the init() function.
2. Expose the current UI translation locale by providing a getViewerContext() hook to the init() function. See our our demo app for example.
   1. NOTE: it's not sufficient to only change the translation payload because we apply various number variation and phonological rules based on the UI locale. I.e. If you forget to change of locale, you might still end up displaying incorrect translations.