fbtee

https://fbtee.dev
Admin
fbtee is an internationalization framework for JavaScript and React designed to be powerful,...
Tokens:4,986
Snippets:57
Trust Score:5.2
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install ESLint plugin

Source: https://fbtee.dev/

Command to install the optional ESLint plugin.

```bash
npm install -D @nkzw/eslint-plugin-fbtee
```

--------------------------------

### Install Vite Plugin and Compiler

Source: https://fbtee.dev/

Installs the native Vite plugin and the fbtee compiler as dev dependencies.

```bash
npm install -D @nkzw/vite-plugin-fbtee @nkzw/fbtee-compiler
```

--------------------------------

### Install fbtee Runtime

Source: https://fbtee.dev/

Command to install the fbtee runtime package. Requires Node 22+ and React 19+ if using React.

```bash
npm install fbtee
```

--------------------------------

### Before: unwrapped string

Source: https://fbtee.dev/

Example of a user-facing string not wrapped in fbt, shown as the 'before' state for the following 'after' example.

```typescript
const Greeting = () => (
  <div>Hello, World!</div>
);
```

--------------------------------

### Create a scoped runtime with LocaleProvider

Source: https://fbtee.dev/

Use createFbteeRuntime and LocaleProvider to give part of a page its own language. Components use the nearest LocaleProvider through useFbt(), and async actions keep the locale they started with.

```typescript
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>
  );
}
```

--------------------------------

### Inline Translation Example with fbt and fbt:plural

Source: https://fbtee.dev/

Shows how to write translatable text inline using fbt components. The compiler extracts strings for translation providers. Includes a plural form with count and showCount attributes.

```jsx
const WelcomeMessage = ({ messageCount, user }) => (
  <div>
    <fbt desc="Welcome message with user component">
      Welcome back, <UserWithAvatar user={user} />!
      You have <fbt:plural
        count={messageCount}
        many="messages"
        name="messageCount"
        showCount="ifMany"
      >
        one message
      </fbt:plural>.
    </fbt>
  </div>
);
```

--------------------------------

### Configure ESLint with recommended config

Source: https://fbtee.dev/

Shows how to import and use the recommended ESLint config from the fbtee plugin.

```javascript
import fbtee from '@nkzw/eslint-plugin-fbtee';

export default [fbtee.configs.recommended];
```

--------------------------------

### Prepare editable translation files

Source: https://fbtee.dev/

Command to prepare editable locale files from source strings, keeping existing translations and adding missing entries with status "new".

```bash
pnpm fbtee prepare-translations --source-strings source_strings.json --output-dir translations --locales de-DE fr-FR ja-JP
```

--------------------------------

### Server rendering with runWithFbtee

Source: https://fbtee.dev/

Use runWithFbtee from 'fbtee/server' to give each server request its own locale, translations, and hooks, including asynchronous calls. Load translations before rendering and initialize the browser with the same locale for hydration.

```typescript
import { runWithFbtee } from 'fbtee/server';
import { renderToString } from 'react-dom/server';
import App from './App.tsx';
import german from './translations/de-DE.json' with { type: 'json' };

export function renderPage() {
  return runWithFbtee(
    { locale: 'de-DE', translations: german },
    () => renderToString(<App />),
  );
}
```

--------------------------------

### Compile translations with pnpm fbtee translate

Source: https://fbtee.dev/

Command to generate optimized runtime files in src/translations/.

```bash
pnpm fbtee translate --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations
```

--------------------------------

### Define common strings with fbt common and compiler config

Source: https://fbtee.dev/

Shows how to define a common string using the <fbt common> tag and pass its description to the compiler via the fbtCommon option.

```javascript
<fbt common>Save</fbt>

// Pass common strings to the compiler:
{
  fbtCommon: {
    Save: 'Button label for saving changes',
  },
}
```

--------------------------------

### Set up createLocaleContext for React apps

Source: https://fbtee.dev/

Use createLocaleContext to define available languages, load translations asynchronously, and wrap the app with the locale context. Preloads the locale before rendering.

```typescript
import { createLocaleContext } from 'fbtee';
import { createRoot } from 'react-dom/client';

// Define available languages
const availableLanguages = new Map([
  ['en-US', 'English'],
  ['de-DE', 'Deutsch'],
  ['ja-JP', '日本語'],
]);

const loadLocale = async (locale: string) => {
  switch (locale) {
    case 'de-DE':
      return (await import('./translations/de-DE.json')).default['de-DE'];
    case 'ja-JP':
      return (await import('./translations/ja-JP.json')).default['ja-JP'];
    default:
      return {};
  }
};

const LocaleContext = createLocaleContext({
  availableLanguages,
  clientLocales: [navigator.language, ...navigator.languages],
  loadLocale,
});

await LocaleContext.preload();

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

--------------------------------

### Vite Configuration with fbtee Plugin

Source: https://fbtee.dev/

Configures Vite to use the fbtee plugin before the React plugin. Includes fbtCommon and fbtEnumManifest options.

```javascript
import fbtee from '@nkzw/vite-plugin-fbtee';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    fbtee({
      fbtCommon: {
        Accept: 'Button label for accepting terms',
      },
      fbtEnumManifest: {},
    }),
    react(),
  ],
});
```

--------------------------------

### Use fbs() for plain strings in HTML attributes

Source: https://fbtee.dev/

Shows how to use fbs() for plain strings in HTML attributes like placeholder, title, and aria-label.

```jsx
import { fbs } from 'fbtee';

<input
  type="text"
  placeholder={fbs('Enter your name', 'Placeholder for name input')}
/>

<button
  title={fbs('Click to save', 'Save button tooltip')}
  aria-label={fbs('Save document', 'Save button accessibility label')}
>
  Save
</button>
```

--------------------------------

### Use <fbt:param> for dynamic values

Source: https://fbtee.dev/

Use <fbt:param> for dynamic values. Token names should describe the value, not its current English position.

```typescript
const UserGreeting = ({ name, score }) => (
  <div>
    <fbt desc="User greeting with score">
      Hello, <fbt:param name="userName">{name}</fbt:param>!
      You have <fbt:param name="userScore">{score}</fbt:param> points.
    </fbt>
  </div>
);
```

--------------------------------

### Extract strings with pnpm fbtee collect

Source: https://fbtee.dev/

Command to extract source strings and write them to source_strings.json.

```bash
pnpm fbtee collect
```

--------------------------------

### Use list() helper for non-React code

Source: https://fbtee.dev/

The standalone list() helper is available for non-React code. It formats a list with the given conjunction and punctuation.

```typescript
import { list } from 'fbtee';

const userList = list(['Alice', 'Bob', 'Charlie'], 'or', 'comma');
// "Alice, Bob, or Charlie"
```

--------------------------------

### Ignore generated runtime output

Source: https://fbtee.dev/

List of files and directories to ignore in version control.

```text
.enum_manifest.json
source_strings.json
src/translations/
```

--------------------------------

### Build locale-aware lists with <fbt:list>

Source: https://fbtee.dev/

Use <fbt:list> to build locale-aware lists. The items prop is an array of strings or React nodes.

```typescript
<fbt desc="People assigned to a task">
  Assigned to <fbt:list items={assignees} name="assigneeList" />.
</fbt>
```

--------------------------------

### Use useLocaleContext to read or change locale

Source: https://fbtee.dev/

Shows how to use useLocaleContext and useTransition to change the locale in a button component.

```jsx
import { useLocaleContext } from 'fbtee';
import { useTransition } from 'react';

const LanguageButton = () => {
  const [, startTransition] = useTransition();
  const { locale, setLocale } = useLocaleContext();

  return (
    <button onClick={() => startTransition(() => setLocale('de-DE'))}>
      {locale}
    </button>
  );
};
```

--------------------------------

### After: wrap strings with <fbt>

Source: https://fbtee.dev/

Wrap user-facing strings in <fbt> with a required desc attribute. <fbt> is auto-imported by the fbtee compiler integration; use fbt() outside JSX.

```typescript
const Greeting = () => (
  <div>
    <fbt desc="Greeting">
      Hello, World!
    </fbt>
  </div>
);
```

--------------------------------

### Coding agent prompt for translating new entries

Source: https://fbtee.dev/

Prompt for coding agents to translate new entries in translation files, matching tone and voice, and removing the status marker.

```text
Run `fbtee prepare-translations --source-strings source_strings.json --output-dir ares/translations --locales de-DE fr-FR ja-JP pl-PL ru-RU zh-CN es-ES it-IT ko-KR pt-BR uk-UA` for all the translations the app supports.

Look at all updated translation files. For every entry with `"status": "new"`, write a translation that matches the tone, voice, and language already used in the app and in the current locale.

Remove `"status": "new"` from each completed translation entry.
```

--------------------------------

### Add JSX type declarations for fbtee

Source: https://fbtee.dev/

Include this reference in a global type file or app entry point for React TypeScript projects to enable JSX type checking for fbtee components.

```typescript
/// <reference types="fbtee/ReactTypes.d.ts" />
```

--------------------------------

### Use <fbt:enum> for fixed label sets

Source: https://fbtee.dev/

Use enums when runtime values map to a fixed set of translatable labels. For shared enum modules, use the $FbtEnum suffix so the collector can resolve them.

```typescript
const StatusLabels = {
  done: 'done',
  open: 'open',
};

<fbt desc="Task status label">
  This task is <fbt:enum enum-range={StatusLabels} value={status} />.
</fbt>;
```

--------------------------------

### Use <fbt:plural> for count-dependent grammar

Source: https://fbtee.dev/

Use <fbt:plural> when a count controls grammar. fbtee handles locale-specific plural rules. showCount can be "yes", "ifMany", or "no".

```typescript
<fbt desc="Inbox unread count">
  You have{' '}
  <fbt:plural
    count={count}
    many="unread messages"
    name="unreadCount"
    showCount="yes"
  >
    an unread message
  </fbt:plural>
  .
</fbt>

// showCount can be "yes", "ifMany", or "no".
```

--------------------------------

### Use <fbt:pronoun> for gender-dependent phrases

Source: https://fbtee.dev/

Use <fbt:pronoun> when a phrase depends on a person's gender. Supported pronoun types are "subject", "object", "possessive", and "reflexive".

```typescript
<fbt desc="Photo sharing notification">
  <fbt:param name="name">{user.name}</fbt:param>
  shared{' '}
  <fbt:pronoun gender={user.gender} human type="possessive" /> photo.
</fbt>

// Supported pronoun types are "subject", "object", "possessive", and "reflexive".
```
Tokens:
Raw