Getting Started on web
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 (byfbt._
) - NOTE: This plugin should get merged into
babel-plugin-fbt
- Transforms the raw payloads within
- @fbtjs/default-collection-transform
- Only required if if you elect not to pass a custom
--transform
nor--custom-collector
in the collection script
- Only required if if you elect not to pass a custom
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:
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
)
- NOTE: Enum modules must end in $FbtEnum.(js|jsx|ts|tsx) (i.e.
- 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
- Takes extracted source text (from
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:
- 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 theinit()
function. - Expose the current UI translation locale by providing a
getViewerContext()
hook to theinit()
function. See our our demo app for example.- 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.