fbtee i18n Framework

For custom build pipelines using Oxc, run the fbtee transform before lowering TypeScript and JSX.

Installation:

npm install -D @nkzw/fbtee-compiler oxc-transform

Implementation Example:

import { transformSync as transformFbtee } from '@nkzw/fbtee-compiler';
import { transformSync as transformOxc } from 'oxc-transform';

export function compile(filename: string, source: string) {
  const translated = transformFbsea(filename, source);
  if (translated.errors.length) {
    throw new Error(translated.errors.map(({ message }) => message).join('\n'));
  }

  return transformOxc(filename, translated.code, {
    jsx: { runtime: 'automatic' },
  });
}

The returned Oxc result contains the generated code and any downstream errors. You can configure common strings and enums via the transform options.

import { transformSync as transformFbtee } from '@nkzw/fbtee-compiler';
import { transformSync as transformOxc } from 'oxc-transform';

export function compile(filename: string, source: string) {
  const translated = transformFbtee(filename, source);
  if (translated.errors.length) {
    throw new Error(translated.errors.map(({ message }) => message).join('\n'));
  }

  return transformOxc(filename, translated.code, {
    jsx: { runtime: 'automatic' },
  });
}

For applications with a single active language, use createLocaleContext to manage locales based on browser preferences.

1. Define availableLanguages as a Map of BCP 47 locales to display names.
2. Provide clientLocales (e.g., navigator.languages) to allow the context to match browser settings.
3. Implement loadLocale as an async function that fetches the translation JSON for a given locale.
4. Crucial: Call await LocaleContext.preload() once before rendering your application to load the initial language and fallback catalogs. Creating the context does not trigger the load automatically.
5. Wrap your application root in the <LocaleContext> provider.

import { createLocaleContext } from 'fbtee';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';

const LocaleContext = createLocaleContext({
  availableLanguages: new Map([
    ['en-US', 'English'],
    ['de-DE', 'Deutsch'],
  ]),
  clientLocales: navigator.languages,
  loadLocale: async (locale) =>
    locale === 'de-DE' ? (await import('./translations/de-DE.json')).default['de-DE'] : {},
});

await LocaleContext.preload();

createRoot(document.getElementById('root')!).render(
  <LocaleContext>
    <App />
  </LocaleContext>,
);

The translation process follows a three-step cycle: extraction, translation, and compilation.

1. Extract Strings

First, collect all strings from your source code and prepare translation files for your target locales.

npx fbtee collect
npx fbtee prepare-translations --source-strings source_strings.json --output-dir translations --locales de-DE ja-JP

2. Translate

Translate the entries in the generated files. Entries marked with "status": "new" should be translated, then the status should be removed.

To compile the translations into your app's runtime format:

npx fbtee translate --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations

Strict Mode: Use --strict to ensure every collected source hash has a completed entry in every locale. This will fail if entries are missing, marked as "status": "new", or have empty translation lists.

3. Commit and Ignore

Commit your editable translation files in translations/. Add the following generated files to your .gitignore:

.enum_manifest.json
source_strings.json
src/translations/

Note on Runtime Catalogs: Generated catalogs omit messages that lack a completed translation (including those marked "status": "new"). This allows partial catalogs to fall back to other languages.

If a specific part of your application needs its own language (independent of the global context), use LocaleProvider.

1. Create a runtime using createFbteeRuntime outside of the render cycle.
2. Wrap the specific component tree in <LocaleProvider runtime={yourRuntime} />.
3. Use the useFbt() hook inside components within that provider to access the scoped translator.

Note: A runtime's locale and gender are fixed. To change them, you must switch the provider's runtime.

import { createFbteeRuntime, LocaleProvider, useFbt } from 'fbtee';
import german from './translations/de-DE.json' with { type: 'json' };

const germanRuntime = createFbteeRuntime({ locale: 'de-DE', translations: german });

function SaveButton() {
  const { fbt } = useFbt();
  return <button>{fbt('Save', 'Save button')}</button>;
}

function Preview() {
  return (
    <LocaleProvider runtime={germanRuntime}>
      <SaveButton />
    </LocaleProvider>
  );
}