### Install fbtee Runtime and Babel Preset

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Install the core fbtee runtime and the Babel preset for integrating with your build process.

```bash
npm install fbtee
npm install -D @nkzw/babel-preset-fbtee
```

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

### Install Dependencies and Build Project

Source: https://github.com/nkzw-tech/fbtee/blob/main/CONTRIBUTING.md

Install project dependencies, build necessary artifacts for testing, and run the test suite.

```bash
pnpm install

# Build everything required for unit tests
pnpm build:all

pnpm test
```

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

### Install fbtee Babel Preset

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Install the Babel preset for fbtee as a development dependency. This is required for the compiler to extract strings.

```bash
npm install -D @nkzw/babel-preset-fbtee
```

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

### Install fbtee npm package

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Install the fbtee package using npm. Ensure you have Node.js 22 or higher.

```bash
npm install fbtee
```

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

### Install fbtee ESLint Plugin

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Install the optional ESLint plugin for fbtee to enforce best practices and catch common mistakes during development.

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

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

### Input Translation File Example

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Example of an input translation file for `fbtee translate` or `fbtee prepare-translations`. It specifies the locale and contains translations keyed by hash.

```json
{
  "fb-locale": "de_DE",
  "translations": {
    "MB6OYuvCF1VzjOmqinI42g==": {
      "tokens": [], "types": [],
      "translations": [{ "translation": "Was kommt jetzt?", "variations": [] }]
    }
  }
}
```

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

### Output Runtime File Example

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Example of an output runtime translation file generated by `fbtee translate`. It contains a mapping from string hashes to their translated text.

```json
{ "de_DE": { "2HVYhv": "Was kommt jetzt?" } }
```

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

### Basic Greeting Component with fbtee

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Example of a React component using fbtee for inline translations. No specific setup is required beyond installing the fbtee package.

```tsx
const Greeting = ({ name }) => (
  <div>
    <fbt desc="Greeting">
      Hello, <Name name={name} />!
    </fbt>
  </div>
);
```

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

### Install Vite React Plugin

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Install the Vite React plugin if you are using Vite for your project. This plugin is used to integrate the fbtee Babel preset.

```bash
npm install -D @vitejs/plugin-react
```

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

### Set Node.js and pnpm Versions

Source: https://github.com/nkzw-tech/fbtee/blob/main/CONTRIBUTING.md

Ensure you have the correct versions of Node.js and pnpm installed for development.

```bash
pnpm env use --global 24
nvm use 24
```

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

### Setup FBTEE with IntlVariations

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use IntlVariations constants to configure viewer context for gender and locale. Ensure translations are provided for the specified locale.

```tsx
import { IntlVariations, setupFbtee } from 'fbtee';

setupFbtee({
  hooks: {
    getViewerContext: () => ({
      GENDER: IntlVariations.GENDER_FEMALE, // 2
      locale: 'fr_FR',
    }),
  },
  translations: { fr_FR: frTranslations },
});

// IntlVariations values:
// GENDER_MALE    = 1
// GENDER_FEMALE  = 2
// GENDER_UNKNOWN = 3
// NUMBER_ONE     = 4
// NUMBER_TWO     = 8
// NUMBER_MANY    = 12
// NUMBER_ZERO    = 16
// NUMBER_FEW     = 20
// NUMBER_OTHER   = 24
```

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

### Complex FBTEE Example

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Demonstrates advanced FBTEE features including <fbt:list>, <fbt:plural>, and <fbt:param> for complex, translatable strings. The example output shows how these components combine to form a coherent sentence.

```tsx
<fbt desc="Feed item">
  <fbt:list items={users} name="userList" />{' '}
  won the game against
  <fbt:plural count={bots} many="bots" name="numberOfBots" showCount="ifMany">
    a bot
  </fbt:plural> on the map
  <fbt:param name="mapName">{game.mapName}</fbt:param>.
</fbt:plural>
// Example Output: "Alice, Bob and Charlie won the game against 2 bots on the map Forest Battle."
```

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

### Allow Meaningful Description for <fbt>

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This example shows a correct usage of `<fbt>` with a meaningful description, which aids translators by providing necessary context.

```jsx
<fbt desc="Greeting">Hello</fbt>
```

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

### Allow Meaningful Description for fbt()

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This example demonstrates the correct usage of the `fbt()` function with a descriptive string, ensuring translators have adequate context.

```javascript
fbt('Hello', 'Greeting');
```

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

### Rule Configuration: Ignored Words

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This configuration example shows how to use the 'ignoredWords' option to specify words that do not need to be translated, preventing false positives.

```javascript
"fbt/no-untranslated-strings": ["warn", { "ignoredWords": ["GitHub"] }]
```

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

### Example Source Strings JSON Structure

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Illustrates the structure of the `source_strings.json` file generated by `fbtee collect`. It maps hashes to phrase details including descriptions and original text.

```json
{
  "childParentMappings": {},
  "phrases": [
    {
      "hashToLeaf": {
        "MB6OYuvCF1VzjOmqinI42g==": {
          "desc": "What's next question",
          "text": "What's next?"
        }
      },
      "col_beg": 12,
      "col_end": 68,
      "filepath": "app/welcome/welcome.tsx",
      "line_beg": 43,
      "line_end": 43,
      "project": "",
      "jsfbt": {
        "m": [],
        "t": {
          "desc": "What's next question",
          "text": "What's next?"
        }
      }
    }
  ]
}
```

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

### Example German Translation JSON

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Demonstrates the structure for a German translation file (`de_DE.json`). Similar to other locales, it maps phrase hashes to the German translation.

```json
{
  "fb-locale": "de_DE",
  "translations": {
    "MB6OYuvCF1VzjOmqinI42g==": {
      "tokens": [],
      "types": [],
      "translations": [
        {
          "translation": "Was kommt jetzt?",
          "variations": []
        }
      ]
    }
  }
}
```

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

### React Locale Provider with createLocaleContext

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Create a React context provider for managing locale state, lazy-loading translations, and handling locale changes. This setup is ideal for React applications.

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

const availableLanguages = new Map([
  ['en_US', 'English'],
  ['de_DE', 'Deutsch'],
  ['ja_JP', '日本語'],
]);

const loadLocale = async (locale: string) => {
  // Lazy-load each locale's compiled translation file
  const mod = await import(`./src/translations/${locale}.json`);
  return mod.default[locale];
};

const LocaleContext = createLocaleContext({
  availableLanguages,
  clientLocales: [navigator.language, ...navigator.languages], // React Native: getLocales().map(l => l.languageTag)
  fallbackLocale: 'en_US',   // defaults to 'en_US' if omitted
  gender: 'unknown',         // 'male' | 'female' | 'unknown'
  loadLocale,
});

export default function App() {
  return (
    <LocaleContext>
      <MyApp />
    </LocaleContext>
  );
}
```

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

### Example US English Translation JSON

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Shows the format for a US English translation file (`en_US.json`). It maps phrase hashes to their translated text, including variations if applicable.

```json
{
  "fb-locale": "en_US",
  "translations": {
    "MB6OYuvCF1VzjOmqinI42g==": {
      "tokens": [],
      "types": [],
      "translations": [
        {
          "translation": "What's next?",
          "variations": []
        }
      ]
    }
  }
}
```

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

### Headless locale management with setupLocaleContext

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

This function provides locale management logic outside of React, suitable for SSR or non-React environments. It handles locale resolution, lazy-loading, and provides functions to get and set the locale and gender. Ensure you provide available languages, client locales, a fallback locale, and a function to load translations.

```ts
import { setupLocaleContext } from 'fbtee';

const { getLocale, setLocale, setGender } = setupLocaleContext({
  availableLanguages: new Map([
    ['en_US', 'English'],
    ['fr_FR', 'Français'],
  ]),
  clientLocales: ['fr-FR', 'en'],
  fallbackLocale: 'en_US',
  loadLocale: async (locale) => {
    const mod = await import(`./src/translations/${locale}.json`);
    return mod.default[locale];
  },
});

console.log(getLocale()); // 'fr_FR' — matched from 'fr-FR' client locale

await setLocale('en_US'); // lazy-loads en_US translations
setGender('female');      // updates gender for pronoun resolution
```

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

### Correct: Translated String with fbt()

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This example demonstrates using the fbt() function to translate a string literal within JSX, providing the string and a description.

```jsx
<h1>{fbt('Hello', 'Greeting')}</h1>
```

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

### Configure Vite with fbtee Preset

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Configure your Vite project to use the fbtee Babel preset via the React plugin. This setup enables fbtee's features within your Vite build process.

```typescript
import fbteePreset from '@nkzw/babel-preset-fbtee';
import react from '@vitejs/plugin-react';

export default {
  plugins: [
    react({
      babel: {
        presets: [fbteePreset],
      },
    }),
  ],
};
```

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

### Setup Custom Locale Context with setupLocaleContext

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Use `setupLocaleContext` to create a custom locale context outside of React components. It accepts similar arguments to the `LocaleContext` component, providing full control over locale management.

```tsx
const { getLocale, setLocale } = setupLocaleContext({
  availableLanguages: AvailableLanguages,
  clientLocales,
  fallbackLocale,
  hooks,
  loadLocale,
  translations,
});

// Now you can call `getLocale` and `setLocale` anytime, even outside of React components.
if (getLocale() === 'en_US') {
  setLocale('ja_JP'); // Switch to Japanese locale
}
```

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

### Incorrect: Template Literal String

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This example shows a template literal string used directly in JSX, which is also considered unwrapped and violates the rule. Template literals must also be handled by fbt.

```jsx
<h1>{`Hello`}</h1>
```

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

### Using GenderConst for Pronouns

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Employ GenderConst for fine-grained gender/personhood values in fbt:pronoun and gendered fbt:param substitutions. This example shows a possessive pronoun.

```tsx
import { GenderConst } from 'fbtee';

// GenderConst values:
// NOT_A_PERSON    = 0  — inanimate objects, "it/its"
// FEMALE_SINGULAR = 1  — "she/her"
// MALE_SINGULAR   = 2  — "he/him"
// UNKNOWN_SINGULAR = 7 — "they/them" (singular unknown)
// UNKNOWN_PLURAL  = 11 — "they/their" (plural unknown)

<fbt desc="Pronoun example">
  <fbt:param name="actor">{actor.name}</fbt:param>
  updated
  <fbt:pronoun type="possessive" gender={GenderConst.FEMALE_SINGULAR} human />
  settings.
</fbt>
// → "Alice updated her settings."
```

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

### Access and switch locale with useLocaleContext

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use this hook inside React components to get the current locale and gender, check if locale changes are pending, and update locale or gender. The localeChangeIsPending flag can be used to provide visual feedback during transitions.

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

function LanguageSwitcher() {
  const { gender, locale, localeChangeIsPending, setGender, setLocale } = 
    useLocaleContext();

  return (
    <div>
      <p>Current locale: {locale}</p>
      <p style={{ opacity: localeChangeIsPending ? 0.5 : 1 }}>
        Gender: {gender}
      </p>

      <button onClick={() => setLocale('de_DE')}>Deutsch</button>
      <button onClick={() => setLocale('ja_JP')}>日本語</button>

      <button onClick={() => setGender('female')}>Female</button>
      <button onClick={() => setGender('male')}>Male</button>
      <button onClick={() => setGender('unknown')}>Unknown</button>
    </div>
  );
}
```

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

### Full fbtee Customization with setupFbtee

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

The `setupFbtee` function provides complete control over fbtee configuration, suitable for non-React environments or advanced customization. It allows setting custom hooks and translations.

```typescript
import { IntlVariations, setupFbtee } from 'fbtee';
import translations from './translations.json';

setupFbtee({
  hooks: {
    getViewerContext: () => ({
      GENDER: IntlVariations.GENDER_UNKNOWN,
      locale: 'en_US',
    }),
  },
  translations,
});
```

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

### Configure Recommended ESLint Plugin

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Add the recommended configuration for the fbtee ESLint plugin to your ESLint configuration file to enable basic checks.

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

export default [
  fbtee.configs.recommended,
  {
    plugins: {
      '@nkzw/fbtee': fbtee,
    },
  },
];
```

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

### setupLocaleContext

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Headless locale management for non-React environments. Handles locale resolution and lazy-loading logic outside of React, suitable for SSR or other platforms.

```APIDOC
## `setupLocaleContext` — Headless locale management (non-React)

`setupLocaleContext` runs the same locale resolution and lazy-loading logic as `createLocaleContext` but outside of React. Returns `getLocale`, `setLocale`, `setGender`, and the resolved initial gender. Suitable for SSR bootstrapping, React Native without context, or game engines.

```tsx
import { setupLocaleContext } from 'fbtee';

const { getLocale, setLocale, setGender } = setupLocaleContext({
  availableLanguages: new Map([
    ['en_US', 'English'],
    ['fr_FR', 'Français'],
  ]),
  clientLocales: ['fr-FR', 'en'],
  fallbackLocale: 'en_US',
  loadLocale: async (locale) => {
    const mod = await import(`./src/translations/${locale}.json`);
    return mod.default[locale];
  },
});

console.log(getLocale()); // 'fr_FR' — matched from 'fr-FR' client locale

await setLocale('en_US'); // lazy-loads en_US translations
setGender('female');      // updates gender for pronoun resolution
```
```

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

### Configure ESLint for Recommended Rules

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Configure ESLint to use the recommended ruleset from the fbtee plugin. This includes rules for no-empty-strings and no-unhelpful-desc.

```javascript
// eslint.config.js — recommended (no-empty-strings + no-unhelpful-desc)
import fbtee from '@nkzw/eslint-plugin-fbtee';

export default [
  fbtee.configs.recommended,
  { plugins: { '@nkzw/fbtee': fbtee } },
];
```

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

### Configure Next.js with fbtee Preset

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Set up your Next.js project to use the fbtee Babel preset by adding it to your `babel.config.js` file. This ensures fbtee is processed during Next.js builds.

```javascript
export default {
  presets: ['next/babel', '@nkzw/babel-preset-fbtee'],
};
```

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

### Prepare Translations with fbtee CLI

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use `fbtee prepare-translations` to generate or update editable translation files. It diffs `source_strings.json` against existing translations, adding new strings and removing obsolete ones. New strings are pre-filled with source text.

```bash
# Create initial translation files for new locales
fbtee prepare-translations --locales de_DE ja_JP fr_FR

# Update existing translation files after adding new strings
fbtee prepare-translations

# Custom source and output paths
fbtee prepare-translations \
  --source-strings i18n/source_strings.json \
  --output-dir i18n/locales/

# New strings appear with status:"new" and the source English text pre-filled:
# {
#   "fb-locale": "de_DE",
#   "translations": {
#     "MB6OYuvCF1VzjOmqinI42g==": {
#       "description": "What's next question",
#       "status": "new",
#       "tokens": [], "types": [],
#       "translations": [{ "translation": "What's next?", "variations": {} }]
#     }
#   }
# }
```

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

### Prepare Translations for Specific Locales

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Generate JSON files for manual translation editing for specified locales. Use this to create or update translation files before processing.

```bash
pnpm fbtee prepare-translations --locales de_DE
```

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

### Configure Vite with Babel Plugin for fbtee

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Alternative Vite configuration using `vite-plugin-babel` for integrating the fbtee Babel preset, useful when not using `@vitejs/plugin-react`.

```typescript
import fbteePreset from '@nkzw/babel-preset-fbtee';
import { reactRouter } from '@react-router/dev/vite';
import { defineConfig } from 'vite';
import babel from 'vite-plugin-babel';

export default defineConfig({
  plugins: [
    babel({ babelConfig: { presets: [fbteePreset] } }),
    reactRouter(),
  ],
});
```

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

### Low-level fbtee Runtime Initialization

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Initialize fbtee directly by registering translation dictionaries and runtime hooks. This is useful for non-React environments or when fine-grained control over the viewer context is needed.

```typescript
import { IntlVariations, setupFbtee } from 'fbtee';
import de_DE from './src/translations/de_DE.json' with { type: 'json' };
import en_US from './src/translations/en_US.json' with { type: 'json' };

setupFbtee({
  hooks: {
    getViewerContext: () => ({
      GENDER: IntlVariations.GENDER_UNKNOWN, // or GENDER_MALE / GENDER_FEMALE
      locale: 'de_DE',
    }),
  },
  translations: {
    de_DE: de_DE.de_DE,
    en_US: en_US.en_US,
  },
});

// All <fbt> and fbt() calls now resolve against the registered translations.
// In a Next.js root layout, call this in a Server Component before rendering children.
```

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

### Collect Translatable Strings with fbtee CLI

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use `fbtee collect` to scan source files for translatable strings and output them to `source_strings.json`. Options include custom source/output paths, common strings manifests, and suppressing default strings.

```bash
# Default: scans CWD, outputs source_strings.json
fbtee collect

# Custom source directory and output path
fbtee collect --src src --out i18n/source_strings.json

# Include a common strings manifest (shared descriptions)
fbtee collect --src src --common src/common_strings.json

# Suppress built-in fbt:list default strings
fbtee collect --include-default-strings=false

# Legacy output format for older translation providers
fbtee collect --legacy-format

# package.json convenience script
# "fbtee:collect": "fbtee collect --src src --out source_strings.json"
```

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

### Translate Collected Strings for App Usage

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Execute this command after preparing translation files. It generates optimized JSON files in `src/translations` for your application to use.

```bash
pnpm fbtee translate
```

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

### Configure ESLint with Granular Rule Settings

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Configure specific ESLint rules from the fbtee plugin with custom options. This allows fine-grained control over translation best practices.

```javascript
// eslint.config.js — granular rule configuration
import fbtee from '@nkzw/eslint-plugin-fbtee';

export default [
  { plugins: { '@nkzw/fbtee': fbtee } },
  {
    rules: {
      // Error on empty <fbt> strings; allow specific branded words
      '@nkzw/fbtee/no-empty-strings': ['error', { ignoredWords: ['GitHub', 'fbtee'] }],

      // Error on non-descriptive desc values like "fbt" or "string"
      '@nkzw/fbtee/no-unhelpful-desc': 'error',

      // Error on any JSX text / string attributes not wrapped with <fbt> / fbt() / fbs()
      '@nkzw/fbtee/no-untranslated-strings': 'error',
    },
  },
];

// no-untranslated-strings catches:
//   ❌ <h1>Hello</h1>            ❌ <span title="Hello" />
//   ✅ <h1><fbt desc="...">Hello</fbt></h1>
//   ✅ <span title={fbs('Hello', 'Greeting')} />
```

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

### Run FBTEE Collect Command

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Execute the fbtee collect command to extract translatable strings from your source files into source_strings.json. This is the initial step before uploading to a translation provider.

```bash
pnpm fbtee collect
```

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

### Basic Dynamic Content Substitution with <fbt:param>

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use <fbt:param> to insert dynamic values into translated strings. This ensures proper word ordering across different locales.

```tsx
// Basic substitution
<fbt desc="User profile sentence">
  <fbt:param name="username">{user.name}</fbt:param>
  updated their profile.
</fbt>
// → "Alice updated their profile."
```

```tsx
// With gender variation (triggers he/she/they branching in translations)
<fbt desc="Photo share sentence">
  <fbt:param name="name" gender={user.gender}>{user.name}</fbt:param>
  shared a photo with you.
</fbt>
```

```tsx
// With number variation
<fbt desc="Score display">
  Score:
  <fbt:param name="score" number={score}>{score}</fbt:param>
</fbt>
```

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

### fbs() / <fbs>

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Produces a plain string rather than a React element. Use for HTML attributes like `placeholder`, `aria-label`, `title`, or in contexts like `alert()`.

```APIDOC
## `fbs()` / `<fbs>` — Plain-text translatable strings

`fbs` (FBT String) is a subset of `fbt` that produces a plain `string` rather than a React element. Use it wherever a plain string is required: `placeholder`, `aria-label`, `title`, `alert()`, etc.

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

// HTML attribute
<input
  type="search"
  placeholder={fbs('Search for anything…', 'Search input placeholder')}
  aria-label={fbs('Search', 'Search input aria-label')}
/>

// alert / non-React string context
window.alert(fbs('Your session has expired.', 'Session expiry alert'));

// <fbs> JSX form (inside JSX trees)
<option value="unknown">
  <fbs desc="Unknown gender option">Unknown</fbs>
</option>
```
```

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

### Set Initial Locale from Stored Preferences

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Initialize the fbtee locale context by pre-selecting the user's preferred locale. This ensures that translations for the chosen locale are loaded eagerly before the initial render.

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

const userLocale = localStorage.getItem('locale') ?? navigator.language;

const loadLocale = async (locale: string) => {
  const mod = await import(`./src/translations/${locale}.json`);
  return mod.default[locale];
};

// Pre-load translations for the chosen locale so the first render is already translated
const translations = { [userLocale]: await loadLocale(userLocale) };

const LocaleContext = createLocaleContext({
  availableLanguages: new Map([['en_US', 'English'], ['de_DE', 'Deutsch']]),
  clientLocales: [userLocale, navigator.language, ...navigator.languages],
  loadLocale,
  translations,
});
```

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

### Configure Vite for fbtee

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Integrate the fbtee Babel preset into your Vite configuration for React projects.

```typescript
import fbteePreset from '@nkzw/babel-preset-fbtee';
import react from '@vitejs/plugin-react';

export default {
  plugins: [
    react({
      babel: { presets: [fbteePreset] },
    }),
  ],
};
```

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

### Correct: Wrapped String with <fbt>

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This code shows the correct way to handle a string literal by wrapping it within an <fbt> tag, including a description for translation.

```jsx
<h1>
  <fbt desc="Greeting">Hello</fbt>
</h1>
```

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

### Configure Granular ESLint Rules

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Manually configure specific rules for the fbtee ESLint plugin to achieve granular control over translation enforcement, including ignored words.

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

export default [
  fbtee,
  {
    plugins: {
      '@nkzw/fbtee': fbtee,
    },
    rules: {
      '@nkzw/fbtee/no-empty-strings': [
        'error',
        {
          ignoredWords: ['Banana', 'pnpm install fbtee'],
        },
      ],
      '@nkzw/fbtee/no-unhelpful-desc': 'error',
      '@nkzw/fbtee/no-untranslated-strings': 'error',
    },
  },
];
```

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

### Translate Strings with fbtee CLI

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Compile translations using `fbtee translate`, reading `source_strings.json` and locale-specific JSON files to generate optimized runtime dictionaries. Supports custom paths, single output files, and strict mode for CI.

```bash
# Default: reads translations/*.json, writes src/translations/<locale>.json
fbtee translate

# Custom paths
fbtee translate \
  --source-strings i18n/source_strings.json \
  --translations i18n/locales/*.json \
  --output-dir src/i18n/

# Single combined output file (no lazy-loading split)
fbtee translate \
  --translations translations/*.json \
  --output-file src/allTranslations.json

# Fail on missing translations (CI use)
fbtee translate --strict

# package.json convenience scripts
# "fbtee:translate": "fbtee translate --translations translations/*.json -o src/translations/"
```

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

### Configure FBTEE Scripts in package.json

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Define custom npm scripts for collecting and translating strings using FBTEE. This allows for easy execution of common translation tasks with specified paths.

```json
{
  "scripts": {
    "fbtee:collect": "fbtee collect --src src",
    "fbtee:translate": "fbtee translate --translations translations/*.json -o src/translations/"
  }
}
```

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

### Create Empty Translation File

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Manually create an empty translation file for a specific locale if you are not using a translation provider. This ensures the file exists for the translate command.

```bash
mkdir -p translations
echo '{"fb-locale": "ja_JP", "translations": {}}' > translations/ja_JP.json
```

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

### Set Initial Locale with ClientLocales

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Set the initial locale for LocaleContext by providing the user's locale, navigator language, and other languages to the clientLocales array. This requires manual loading of translations.

```tsx
// Read the user locale from localStorage etc.
const userLocale = localStorage.getItem('locale');
const LocaleContext = createLocaleContext({
  availableLanguages,
  clientLocales: [userLocale, navigator.language, ...navigator.languages],
  loadLocale,
});
```

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

### Render List with <fbt:list>

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Renders a list of items with specified conjunction and delimiter. The 'name' attribute is required for translator context.

```tsx
<fbt:list
  conjunction="or"
  delimiter="comma"
  items={['Alice', 'Bob', <CharlieNameExampleComponent key="charlieUserID" />]}
  name="userList"
/> // "Alice, Bob, or Charlie"
```

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

### Configure ESLint for Strict Rules

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Configure ESLint to use the strict ruleset, which includes the no-untranslated-strings rule in addition to the recommended rules.

```javascript
// eslint.config.js — strict (adds no-untranslated-strings)
import fbtee from '@nkzw/eslint-plugin-fbtee';

export default [
  fbtee.configs.strict,
  { plugins: { '@nkzw/fbtee': fbtee } },
];
```

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

### Incorrect: fbt() call with empty string

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-empty-strings.md

This rule flags fbt() calls where the first argument, the text to translate, is an empty string.

```javascript
fbt('', 'Greeting');
```

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

### Use fbs() for Plain Text Strings

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Employ the `fbs()` function for plain text strings when not using React components, such as for input placeholders or alert dialogs. It's a subset of `fbt` supporting only plain text.

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

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

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

### Configure Strict ESLint Plugin

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Use the strict configuration for the fbtee ESLint plugin to enforce stricter translation rules, including the no-untranslated-strings rule.

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

export default [
  fbtee.configs.strict,
  {
    plugins: {
      '@nkzw/fbtee': fbtee,
    },
  },
];
```

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

### Insert Dynamic Content with <fbt:param>

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Uses <fbt:param> to insert dynamic content, such as a user's name, into a translatable string. The 'name' attribute is required.

```tsx
const Greeting = ({ name }) => (
  <div>
    <fbt desc="Greeting">
      Hello, <fbt:param name="name">{name}</fbt:param>!
    </fbt>
  </div>
);
```

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

### Add FBTEE Generated Files to .gitignore

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Ensure that generated translation files and intermediate files are not committed to version control by adding them to your .gitignore file.

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

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

### Locale-Aware List Rendering with <fbt:list> and list()

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Render arrays as grammatically correct lists using <fbt:list> in JSX or the standalone list() function. Customize conjunctions, delimiters, and serial commas.

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

// JSX form — inside an <fbt> parent
<fbt desc="Share prompt">
  Do you want to share{' '}
  <fbt:list
    conjunction="or"
    delimiter="comma"
    items={['a photo', 'a link', 'a video']}
    name="shareOptions"
  />?
</fbt>
// → "Do you want to share a photo, a link, or a video?"
```

```tsx
// With React elements as items
<fbt:list
  conjunction="and"
  items={
    [
      <strong key="alice">Alice</strong>,
      <strong key="bob">Bob</strong>,
      <strong key="charlie">Charlie</strong>,
    ]
  }
  name="participants"
/>
// → "<strong>Alice</strong>, <strong>Bob</strong> and <strong>Charlie</strong>"
```

```javascript
// Standalone list() function
const result = list(['Paris', 'London', 'Tokyo'], 'and', 'comma');
```

```javascript
// With serial (Oxford) comma
const oxford = list(['red', 'white', 'blue'], 'and', 'comma', { serialComma: true });
// → "red, white, and blue"
```

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

### Manually Load Translations for Initial Locale

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

When setting the initial locale, manually load translations using a loadLocale function. This ensures translations are available on context creation.

```tsx
const loadLocale = async (locale: string) => {
  if (locale === 'ja_JP') {
    return (await import('./translations/ja_JP.json')).default.ja_JP;
  }
  return {};
};

const translations = {
  [userLocale]: await loadLocale(userLocale),
};

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

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

### Basic React Component

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

A standard React component without any FBTEE internationalization.

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

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

### Handle Singular and Plural Forms with <fbt:plural>

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Manages singular and plural forms of a word based on a count. The 'many' prop specifies the plural form, and 'showCount' controls count visibility. The 'name' attribute is required.

```tsx
<fbt desc="end turn confirmation">
  Do you want to play against
  <fbt:plural count={bots} many="bots" name="numberOfBots" showCount="ifMany">
    a bot
  </fbt:plural>?
</fbt>
```

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

### Optimized Translation File Structure

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Presents the optimized JSON structure for translated strings, typically found in `src/translations`. This format is ready for direct use within the application.

```json
{
  "de_DE": {
    "2HVYhv": "Was kommt jetzt?"
  }
}
```

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

### FBTEE List Function for Non-React Context

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Provides a 'list' function for rendering lists outside of React components. It accepts items, conjunction, and delimiter as arguments.

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

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

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

### fbt() function

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

The non-JSX equivalent of `<fbt>`, usable in event handlers, arrays, or anywhere JSX elements cannot appear. Transformed at compile time by the Babel plugin.

```APIDOC
## `fbt()` function — Translatable strings outside JSX

The `fbt()` function is the non-JSX equivalent of `<fbt>`, usable in event handlers, arrays, or anywhere JSX elements cannot appear. The Babel plugin transforms it at compile time.

```tsx
import { fbt } from 'fbtee';

// Basic usage: fbt(string, description)
const label = fbt('Submit', 'Form submit button label');

// In a button
<button type="submit">{fbt('Save changes', 'Save button')}</button>

// With JSX interpolation for dynamic content
const count = 3;
const msg = fbt(
  fbt.param('count', count) + ' items selected',
  'Selection count message',
);
```
```

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

### Initialize FBTEE LocaleContext in React App

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Set up the LocaleContext component to manage the application's locale. This involves defining available languages, detecting client locales, and providing a function to load translations.

```tsx
import { getLocales } from 'expo-localization';
import { createLocaleContext } from 'fbtee';

// Define the available languages in your app:
const availableLanguages = new Map([
  ['en_US', 'English'],
  ['ja_JP', '日本語 (Japanese)'],
]);

// Web:
const clientLocalesWeb = [navigator.language, ...navigator.languages];
// React Native:
const clientLocalesRN = getLocales().map(({ languageTag }) => languageTag);

// A loader function to fetch translations for a given locale:
const loadLocale = async (locale: string) => {
  if (locale === 'ja_JP') {
    return (await import('./translations/ja_JP.json')).default.ja_JP;
  }

  return {};
};

const LocaleContext = createLocaleContext({
  availableLanguages,
  clientLocales: clientLocalesWeb, // or clientLocalesRN for React Native
  loadLocale,
});

// Now wrap your app with `LocaleContext`:
const MyAppEntryPoint = () => (
  <LocaleContext>
    <App />
  </LocaleContext>
);

```

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

### Wrap String with <fbt>

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Wraps a simple string with the <fbt> component for translation. The 'desc' attribute is required for translator context.

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

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

### Enable fbtee JSX Types in TypeScript

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Add a type reference to your TypeScript project to enable recognition of fbtee's JSX elements like <fbt> and <fbt:param>.

```typescript
// src/index.tsx or a global types.d.ts
/// <reference types="fbtee/ReactTypes.d.ts" />
```

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

### Add FBTEE TypeScript Types Reference

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Include a reference to FBTEE's TypeScript definition file in your main index.tsx or a global type declaration file to enable type checking for FBTEE components and hooks in a React/TypeScript project.

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

```

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

### Incorrect: Empty <fbt> tag

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-empty-strings.md

This rule flags <fbt> tags that are empty and do not contain any text content.

```jsx
<fbt desc="Greeting"></fbt>
```

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

### Disallow Empty Description for fbt()

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This rule flags `fbt()` function calls with an empty description string. Always provide a descriptive string for translation context.

```javascript
fbt('Hello world', '');
```

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

### Setting Gender in createLocaleContext

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

The `createLocaleContext` function supports setting the user's gender. Supported values are 'male', 'female', or 'unknown'.

```typescript
createLocaleContext({
  …
  gender: 'female', // 'male', 'female' or 'unknown' are supported.
});
```

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

### Plain-text translatable strings with fbs() / <fbs>

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use `fbs` (FBT String) for translatable strings that should result in a plain JavaScript string, not a React element. This is ideal for HTML attributes like `placeholder`, `aria-label`, `title`, or for use in non-React contexts like `alert()`. The `<fbs>` JSX form can be used within JSX trees.

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

// HTML attribute
<input
  type="search"
  placeholder={fbs('Search for anything…', 'Search input placeholder')}
  aria-label={fbs('Search', 'Search input aria-label')}
/>

// alert / non-React string context
window.alert(fbs('Your session has expired.', 'Session expiry alert'));

// <fbs> JSX form (inside JSX trees)
<option value="unknown">
  <fbs desc="Unknown gender option">Unknown</fbs>
</option>
```

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

### useLocaleContext

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Access and switch locale and gender within React components. Provides current locale, gender, pending state for transitions, and setters for locale and gender.

```APIDOC
## `useLocaleContext` — Access and switch locale inside components

The `useLocaleContext` hook provides the current `locale`, `gender`, a `localeChangeIsPending` flag (React transition state), and setters for locale and gender.

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

function LanguageSwitcher() {
  const { gender, locale, localeChangeIsPending, setGender, setLocale } = 
    useLocaleContext();

  return (
    <div>
      <p>Current locale: {locale}</p>
      <p style={{ opacity: localeChangeIsPending ? 0.5 : 1 }}>
        Gender: {gender}
      </p>

      <button onClick={() => setLocale('de_DE')}>Deutsch</button>
      <button onClick={() => setLocale('ja_JP')}>日本語</button>

      <button onClick={() => setGender('female')}>Female</button>
      <button onClick={() => setGender('male')}>Male</button>
      <button onClick={() => setGender('unknown')}>Unknown</button>
    </div>
  );
}
```
```

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

### Correct: Translated String in Attribute with fbs()

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This shows how to correctly use the fbs() function to translate a string literal used within a JSX attribute, ensuring it's marked for translation.

```jsx
<span title={fbs('Hello', 'Greeting')} />
```

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

### Handle Pronouns with fbt:pronoun

Source: https://github.com/nkzw-tech/fbtee/blob/main/README.md

Use `<fbt:pronoun>` to manage gendered pronouns in translations. Ensure the `gender` attribute is correctly set based on user data.

```tsx
<fbt desc="Photo sharing text">
  <fbt:param name="name">{user.name}</fbt:param>
  shared
  <fbt:pronoun type="possessive" gender={user.pronounGender} human />
  photo with you.
</fbt>
```

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

### Incorrect: <fbt> tag with empty string

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-empty-strings.md

This rule flags <fbt> tags that explicitly contain only an empty string.

```jsx
<fbt desc="Greeting">{''}</fbt>
```

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

### Disallow Generic Description for fbt()

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This rule flags `fbt()` function calls where the description string is generic or identical to the text. Use specific descriptions to aid translators.

```javascript
fbt('Hello world', 'foo');
```

```javascript
fbt('Hello world', 'hello world');
```

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

### Handling Plural Forms with <fbt:plural>

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Employ <fbt:plural> for count-based singular/plural inflection, supporting languages with complex plural categories. The 'showCount' attribute controls visibility of the count.

```tsx
// showCount="ifMany": count visible only in plural case
<fbt desc="Bot count in game">
  Do you want to play against
  <fbt:plural count={botCount} many="bots" name="numberOfBots" showCount="ifMany">
    a bot
  </fbt:plural>?
</fbt>
// count=1 → "Do you want to play against a bot?"
// count=3 → "Do you want to play against 3 bots?"
```

```tsx
// showCount="yes": always show count
<fbt desc="Photo count">
  You have
  <fbt:plural count={photoCount} many="photos" name="photoCount" showCount="yes">
    1 photo
  </fbt:plural>.
</fbt>
// count=1 → "You have 1 photo."
// count=7 → "You have 7 photos."
```

```tsx
// showCount="no": never show count
<fbt desc="Notification">
  You have
  <fbt:plural count={n} many="new notifications" name="notifCount" showCount="no">
    a new notification
  </fbt:plural>.
</fbt>
```

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

### Disallow Empty Description for <fbt>

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This rule flags `<fbt>` elements with an empty `desc` attribute. Provide a meaningful description for translation context.

```jsx
<fbt desc="">Hello world</fbt>
```

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

### Translatable strings outside JSX with fbt() function

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

The `fbt()` function serves as the non-JSX equivalent of `<fbt>`, useful in contexts where JSX is not allowed, such as event handlers or arrays. It is transformed by the Babel plugin at compile time. Use `fbt.param()` for interpolating dynamic content.

```ts
import { fbt } from 'fbtee';

// Basic usage: fbt(string, description)
const label = fbt('Submit', 'Form submit button label');

// In a button
<button type="submit">{fbt('Save changes', 'Save button')}</button>

// With JSX interpolation for dynamic content
const count = 3;
const msg = fbt(
  fbt.param('count', count) + ' items selected',
  'Selection count message',
);
```

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

### Disallow Generic Description for <fbt>

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unhelpful-desc.md

This rule flags `<fbt>` elements where the `desc` attribute is a generic string like 'foo' or identical to the text content. Ensure descriptions offer unique context for translators.

```jsx
<fbt desc="foo">Hello world</fbt>
```

```jsx
<fbt desc="Hello world">Hello world</fbt>
```

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

### Incorrect: Unwrapped String Literal

Source: https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/no-unwrapped-strings.md

This code demonstrates an unwrapped string literal within JSX, which violates the rule. All strings intended for translation must be enclosed.

```jsx
<h1>Hello</h1>
```

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

### Inline translatable strings with <fbt> JSX element

Source: https://context7.com/nkzw-tech/fbtee/llms.txt

Use the `<fbt>` element to mark JSX text for translation. The `desc` attribute is required for translator context. The Babel plugin handles extraction, and `fbtee` auto-imports the element. Dynamic parameters can be included using `<fbt:param>` or by embedding React components directly.

```tsx
// Simple string
const Welcome = () => (
  <h1>
    <fbt desc="Welcome heading">Welcome to our app!</fbt>
  </h1>
);

// Common strings — description sourced from an external common_strings.json manifest
const Tagline = () => (
  <p>
    <fbt common>Use the form below to see fbtee in action.</fbt>
  </p>
);

// Dynamic parameter with gender variation
const ShareNotice = ({ user }: { user: { name: string; gender: GenderConst } }) => (
  <p>
    <fbt desc="Share notice">
      <fbt:param name="name" gender={user.gender}> 
        <strong>{user.name}</strong>
      </fbt:param>
      shared their profile with you.
    </fbt>
  </p>
);

// Implicit param — any React component inside <fbt> auto-becomes an fbt:param
const Greeting = ({ name }: { name: string }) => (
  <div>
    <fbt desc="Greeting">
      Hello, <Name name={name} />!
    </fbt>
  </div>
);
```