@nkzw/eslint-plugin-fbtee 1.8.0 → 2.0.0

package/README.md

@@ -1,90 +1,87 @@
 # fbtee
 
-_**fbtee** (Far Better Translations, Extended Edition) is an internationalization framework for JavaScript & React designed to be **powerful**, **flexible**, and **intuitive**._
-
-fbtee features inline translations and supports dynamic content, pluralization, lists, and more. It is built on top of Facebook's `fbt` library, which has been used in production for over a decade, serving billions of users.
+**_fbtee_** is an internationalization framework for JavaScript and React. It lets you write translatable text inline, keep translator context next to the UI, and compile strings into a small runtime format for production.
 
 ```tsx
 const Greeting = ({ name }) => (
-  <div>
-    <fbt desc="Greeting">
-      Hello, <Name name={name} />!
-    </fbt>
-  </div>
+  <fbt desc="Greeting on the home screen">
+    Hello, <Name name={name} />!
+  </fbt>
 );
 ```
 
-## Why choose **fbtee**?
+_fbtee_ is a modern continuation of Facebook's `fbt`, rebuilt for TypeScript, ESM, React 19, Vite, Next.js, Babel & SWC.
+
+## Features
 
 - **Inline translations for Better Developer Experience:** Embed translations directly into your code. No need to manage translation keys or wrap your code with `t()` functions. **fbtee** uses a compiler to extract strings from your code and prepare them for translation providers.
-- **Proven in Production:** Built on Facebook's `fbt`, with over a decade of production usage, serving billions of users and two years of production usage in [Athena Crisis](https://athenacrisis.com).
+- **Proven in Production:** Built on Facebook's `fbt`, with over a decade of production usage serving billions of users, plus years in production at [Athena Crisis](https://athenacrisis.com).
 - **Optimized Performance with IR:** Compiles translations into an Intermediate Representation (IR) for extracting strings, then optimizes the runtime output for performance.
-- **Easy Setup:** Quick integration with tools like Babel and Vite means you can get started instantly.
+- **Easy Setup:** Quick integration with Babel, SWC, Vite, Next.js, and Expo.
 
 ## Getting Started
 
-Tired of setting up new projects? Check out these templates for web and React Native that come with **fbtee** pre-configured:
+Use one of the templates if you are starting fresh:
 
 - [Web App Template](https://github.com/nkzw-tech/web-app-template)
 - [Expo App Template](https://github.com/nkzw-tech/expo-app-template)
 
-### Examples
+For an existing app, install the runtime:
 
-Sometimes it's easiest to learn by example and copy-paste the setup from existing projects. Here are some examples of using **fbtee**:
+```bash
+npm install fbtee
+```
 
-- [Next.js App fbtee Example](https://github.com/cpojer/nextjs-fbtee-example) - A Next.js App Router example using **fbtee** with Server Components.
-- [Athena Crisis](https://github.com/nkzw-tech/athena-crisis) - an open source video game using **fbtee**
+_fbtee_ requires Node 22+. React apps should use React 19+.
 
-### Installation
+### Babel, Vite and React
 
-**fbtee** requires at least Node 22, and React 19 if you are using React.
+Install the Babel preset and the Rolldown Babel plugin:
 
 ```bash
-npm install fbtee
+npm install -D @nkzw/babel-preset-fbtee @rolldown/plugin-babel
 ```
 
-In addition to `fbtee`, you need to install the compiler integration for your build tool. For Babel-based builds, install the Babel preset. This keeps the existing `fbtee` CLI commands available through the Babel tooling package:
+With Vite, `@rolldown/plugin-babel`, and `@vitejs/plugin-react`:
 
-```bash
-npm install -D @nkzw/babel-preset-fbtee
+```ts
+import fbteePreset from '@nkzw/babel-preset-fbtee';
+import babel from '@rolldown/plugin-babel';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    babel({
+      presets: [fbteePreset],
+    }),
+    react(),
+  ],
+});
 ```
 
-For SWC or Turbopack builds, install the SWC plugin and the standalone CLI package:
+With a direct Babel setup:
 
-```bash
-npm install -D @nkzw/swc-plugin-fbtee @nkzw/fbtee-cli
+```js
+export default {
+  presets: ['@nkzw/babel-preset-fbtee'],
+};
 ```
 
-### Tooling Setup
+With Next.js and Babel:
 
-#### Using **fbtee** with SWC or Turbopack
+```js
+export default {
+  presets: ['next/babel', '@nkzw/babel-preset-fbtee'],
+};
+```
 
-Use the SWC plugin when your build pipeline runs through SWC instead of Babel, such as Turbopack. Phrase extraction still uses `fbtee collect`; install `@nkzw/fbtee-cli` for SWC-only projects that do not install the Babel preset. The SWC plugin is the runtime compiler that lowers `fbt` and `<fbt>` callsites during application builds.
+### SWC and Turbopack
 
-For raw SWC configuration:
+Install the SWC runtime compiler and the CLI:
 
-```json
-{
-  "jsc": {
-    "experimental": {
-      "plugins": [
-        [
-          "@nkzw/swc-plugin-fbtee",
-          {
-            "fbtCommon": {
-              "Accept": "Button/Link: Accept conditions"
-            },
-            "fbtEnumManifest": {}
-          }
-        ]
-      ]
-    },
-    "parser": {
-      "syntax": "typescript",
-      "tsx": true
-    }
-  }
-}
+```bash
+npm install -D @nkzw/swc-plugin-fbtee @nkzw/fbtee-cli
 ```
 
 For Next.js SWC plugins:
@@ -97,7 +94,7 @@ export default {
         '@nkzw/swc-plugin-fbtee',
         {
           fbtCommon: {
-            Accept: 'Button/Link: Accept conditions',
+            Accept: 'Button label for accepting terms',
           },
           fbtEnumManifest: {},
         },
@@ -107,655 +104,316 @@ export default {
 };
 ```
 
-Do not pass `collectFbt: true` to the SWC plugin. Use `fbtee collect` for extraction and the SWC plugin for compiling app code.
+Use the SWC plugin to compile app code. Use `fbtee collect` to extract phrases. Do not pass `collectFbt: true` to the SWC plugin.
 
-#### Using **fbtee** with Vite
+### TypeScript JSX Types
 
-If you are using Vite, install the React plugin for Vite:
-
-```bash
-npm install -D @vitejs/plugin-react
-```
-
-In your `vite.config.ts`:
-
-```ts
-import fbteePreset from '@nkzw/babel-preset-fbtee';
-import react from '@vitejs/plugin-react';
-
-export default {
-  plugins: [
-    react({
-      babel: {
-        presets: [fbteePreset],
-      },
-    }),
-  ],
-};
-```
-
-#### Using Babel directly instead of Vite's React Plugin
-
-If you are not using `@vitejs/plugin-react`, for example, because you are using the latest version of React Router in framework mode, you can use `vite-plugin-babel` instead:
+React TypeScript projects should include the JSX declarations once in a global type file or app entry point:
 
 ```tsx
-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(),
-  ],
-});
+/// <reference types="fbtee/ReactTypes.d.ts" />
 ```
 
-#### Using **fbtee** with Next.js and Babel
+## Writing Strings
 
-Create a `babel.config.js` file in the root of your Next.js project and add the **fbtee** preset:
+Every user-facing string should be wrapped in `<fbt>`, `fbt()`, or `fbs()`. Descriptions are required because they are the translator's context.
 
 ```tsx
-export default {
-  presets: ['next/babel', '@nkzw/babel-preset-fbtee'],
-};
-```
-
-#### Scripts
-
-**fbtee** uses two scripts to manage translations. These scripts help automate the process of collecting, creating, and compiling translations.
-
-- `fbtee collect`: This command reads your source files and extracts all the translatable strings into a `source_strings.json` file. This file should be uploaded to your translation provider as the source for your translations.
-- `fbtee translate`: This command takes the collected strings and your translations, and compiles them into an optimized format for use in your application.
-
-By default, **fbtee** expects your source code to be anywhere within your project, your translations in a `translations` folder, and the generated translations in `src/translations`. You can customize these paths using command line arguments:
-
-- The `--translations` parameter can be specified to `fbtee translate` to customize the path to the input translation files.
-- The `--output-dir` parameter defines where the output translation files per language should be written (one file per locale), so they can be lazy loaded in your app.
-- The `--output-file` parameter outputs all translations in a single combined file, which can be used directly in your app without loading individual files.
-
-If you want to use different paths, it is recommended to define custom commands in your `package.json`:
-
-```json
-{
-  "scripts": {
-    "fbtee:collect": "fbtee collect --src src",
-    "fbtee:translate": "fbtee translate --translations translations/*.json -o src/translations/"
-  }
-}
+<fbt desc="Empty state title when a project has no tasks">No tasks yet</fbt>
 ```
 
-Now, run the collect command to set up the initial strings for translation:
-
-```bash
-pnpm fbtee collect
-```
-
-Add the files generated by these commands to your `.gitignore`:
-
-```
-.enum_manifest.json
-source_strings.json
-src/translations/
-```
-
-Because no translations exist yet, you can run this command to create an empty file for now:
-
-```bash
-mkdir -p translations
-echo '{"fb-locale": "ja_JP", "translations": {}}' > translations/ja_JP.json
-```
-
-If you are not using a translation provider, you can also run `fbtee prepare-translations --locales ja_JP` to generate a JSON file that can be edited directly.
-
-### App Setup
-
-**fbtee**'s runtime can manage the currently selected locale for you through the `<LocaleContext />` component. All you need to do is define the available languages, the locales provided by the browser or device, and a function to load translations for a given locale:
+Use `fbt()` outside JSX:
 
 ```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)'],
-]);
+import { fbt } from 'fbtee';
 
-// 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>
+const title = fbt(
+  'No tasks yet',
+  'Empty state title when a project has no tasks',
 );
 ```
 
-If you need to access the current locale or set the locale, you can use the `useLocaleContext` hook:
+Use `fbs()` when you need a plain string:
 
 ```tsx
-import { useLocaleContext } from 'fbtee';
-
-const MyComponent = () => {
-  const { locale, setLocale } = useLocaleContext();
-
-  return (
-    <div>
-      <p>Current Locale: {locale}</p>
-      <button onClick={() => setLocale('ja_JP')}>Switch to Japanese</button>
-    </div>
-  );
-};
-```
-
-Next up, if you are using React and TypeScript in your project, you need to add TypeScript types for **fbtee** to enable proper type checking in JSX. You can do this by referencing the `ReactTypes.d.ts` file in your main `index.tsx` file or a global type declaration file (e.g., `types.d.ts`):
+import { fbs } from 'fbtee';
 
-```tsx
-/// <reference types="fbtee/ReactTypes.d.ts" />
+<input
+  placeholder={fbs('Search projects', 'Project search input placeholder')}
+/>;
 ```
 
-_You’re now ready to define your first translatable element!_
+## Dynamic Content
 
-### Alternative Setup Methods
-
-If you need to build your own locale context with custom functionality, you can use the `setupLocaleContext` function. It takes the same arguments as the `LocaleContext` component, but gives you full control over how you manage locales.
+Use `<fbt:param>` for dynamic values. Token names should describe the value, not its current English position.
 
 ```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
-}
+<fbt desc="Greeting with the viewer name">
+  Hello, <fbt:param name="viewerName">{viewer.name}</fbt:param>!
+</fbt>
 ```
 
-A full example of using `setupLocaleContext` to build your own `LocaleContext` abstraction can be found in the [Athena Crisis](https://github.com/nkzw-tech/athena-crisis/blob/main/hera/i18n/LocaleContext.tsx#L41) repository.
-
-### Gender Variations
-
-`createLocaleContext` and `setupLocaleContext` also support setting the user's gender:
+React elements inside `<fbt>` are automatically turned into implicit params:
 
 ```tsx
-createLocaleContext({
-  …
-  gender: 'female', // 'male', 'female' or 'unknown' are supported.
-});
+<fbt desc="Greeting with a linked viewer name">
+  Hello, <UserLink user={viewer} />!
+</fbt>
 ```
 
-If you need to adjust the user's gender dynamically, you can use the `setGender` function provided by the `useLocaleContext` hook:
+Use `fbt.sameParam()` or `<fbt:same-param>` when the same token appears more than once.
 
-```tsx
-import { useLocaleContext } from 'fbtee';
+## Plurals
 
-const GenderSelector = () => {
-  const { gender, setGender } = useLocaleContext();
-
-  return (
-    <div>
-      <button onClick={() => setGender('male')}>
-        <fbt desc="Male gender">Male</fbt>
-      </button>
-      <button onClick={() => setGender('female')}>
-        <fbt desc="Female gender">Female</fbt>
-      </button>
-      <button onClick={() => setGender('unknown')}>
-        <fbt desc="Unknown gender">Unknown</fbt>
-      </button>
-    </div>
-  );
-};
-```
-
-#### Full Customization
-
-Finally, if you are using something other than React, or need even more control over how **fbtee** is configured, you can use the `setupFbtee` function. This function allows you to set up **fbtee** with custom hooks and translations:
+Use `<fbt:plural>` when a count controls grammar. _fbtee_ handles locale-specific plural rules.
 
 ```tsx
-import { IntlVariations, setupFbtee } from 'fbtee';
-import translations from './translations.json';
-
-setupFbtee({
-  hooks: {
-    getViewerContext: () => ({
-      GENDER: IntlVariations.GENDER_UNKNOWN,
-      locale: 'en_US',
-    }),
-  },
-  translations,
-});
+<fbt desc="Inbox unread count">
+  You have{' '}
+  <fbt:plural
+    count={count}
+    many="unread messages"
+    name="unreadCount"
+    showCount="yes"
+  >
+    an unread message
+  </fbt:plural>
+  .
+</fbt>
 ```
 
-### Usage with Next.js
-
-If you are using Next.js with App Router, check out the [Next.js App fbtee Example](https://github.com/cpojer/nextjs-fbtee-example). You'll need to set up a `<LocaleContext />` as a Client Component, and call `setupFbtee` in the root layout of your app for Server Component support.
-
-When using Next.js with **fbtee**, translated strings are inserted when your Server Components are rendered. This means that changing locales on the client will not automatically update the Server Component's translated strings. To handle locale changes, you need to call a server action that updates the locale, and then re-render your app with the new locale, for example by reloading the page.
-
-If you are exclusively using **fbtee** within Client Components, you can handle locale changes directly on the client only.
-
-## Usage
-
-_If you want to learn by example, check out the [examples](https://github.com/nkzw-tech/fbtee/tree/main/example) directory. You can also check out [Athena Crisis](https://github.com/nkzw-tech/athena-crisis), a large open source video game using **fbtee**_
+`showCount` can be `yes`, `ifMany`, or `no`.
 
-With **fbtee**, all strings must be wrapped using `<fbt>` (for React/JSX) or `fbt()` (for JavaScript). This ensures strings can be extracted and translated properly. The `desc` attribute is required and provides context for translators, helping them understand the intended meaning of the string.
+## Lists
 
-Here are some basic examples:
+Use `<fbt:list>` for locale-aware lists:
 
 ```tsx
-const Greeting = () => <div>Hello, World!</div>;
+<fbt desc="People assigned to a task">
+  Assigned to <fbt:list items={assignees} name="assigneeList" />.
+</fbt>
 ```
 
-You can wrap the string with `<fbt>`:
+The standalone `list()` helper is available for non-React code:
 
 ```tsx
-const Greeting = () => (
-  <div>
-    <fbt desc="Greeting">Hello, World!</fbt>
-  </div>
-);
-```
-
-`<fbt>` is a special React component that marks text for translation. The **fbtee** compiler analyzes them to extract strings, and compiles them into an Intermediate Representation (IR). Here is a more complex example of what you can do with **fbtee**:
+import { list } from 'fbtee';
 
-```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."
+const names = list(['Alice', 'Bob', 'Charlie'], 'or', 'comma');
 ```
 
-_Note: `<fbt>` is auto-imported for you by the fbtee compiler integration._
+## Enums
 
-This example highlights several features of **fbtee**:
+Use enums when runtime values map to a fixed set of translatable labels:
 
-- `<fbt:list>`: Renders a list of items, automatically handling conjunctions and delimiters.
-- `<fbt:plural>`: Handles singular and plural forms based on a count value.
-- `<fbt:param>`: Allows you to insert dynamic content into your strings, such as variables or React components.
+```tsx
+const StatusLabels = {
+  done: 'done',
+  open: 'open',
+};
 
-With the above components, you can handle complex strings that are translatable into multiple languages while maintaining clarity and context for translators. This sentence structure supports many variations, such as "Alice is playing on Forest Battle.", or "Alice, Bob and Charlie are playing on Giant Crisis".
+<fbt desc="Task status label">
+  This task is <fbt:enum enum-range={StatusLabels} value={status} />.
+</fbt>;
+```
 
-Let's look at each of these features in detail:
+For shared enum modules, use the `$FbtEnum` suffix so the collector can resolve them.
 
-### Dynamic Content
+## Pronouns and Gender
 
-**fbtee** supports dynamic content through <fbt:param> or by using other React components within your text. For example, if you want to greet a specific user based on a name passed as a prop, you can use `<fbt:param>`:
+Use `<fbt:pronoun>` when a phrase depends on a person's gender:
 
 ```tsx
-const Greeting = ({ name }) => (
-  <div>
-    <fbt desc="Greeting">
-      Hello, <fbt:param name="name">{name}</fbt:param>!
-    </fbt>
-  </div>
-);
+<fbt desc="Photo sharing notification">
+  <fbt:param name="name">{user.name}</fbt:param> shared{' '}
+  <fbt:pronoun gender={user.gender} human type="possessive" /> photo.
+</fbt>
 ```
 
-**fbtee** allows you to use regular React Components inside of `<fbt>` which will automatically create `<fbt:param>` calls for you:
+Supported pronoun types are `subject`, `object`, `possessive`, and `reflexive`.
 
-```tsx
-const Greeting = ({ name }) => (
-  <div>
-    <fbt desc="Greeting">
-      Hello, <Name name={name} />!
-    </fbt>
-  </div>
-);
-```
+## Common Strings
 
-### Lists
-
-`<fbt:list>` is used to render a list of items with conjunctions and delimiters. It automatically handles the grammatical structure of the list based on the locale:
+Common strings are reusable source strings with shared descriptions:
 
 ```tsx
-<fbt:list
-  conjunction="or"
-  delimiter="comma"
-  items={['Alice', 'Bob', <CharlieNameExampleComponent key="charlieUserID" />]}
-  name="userList"
-/> // "Alice, Bob, or Charlie"
+<fbt common>Save</fbt>
 ```
 
-The default conjunction is "and", and the default delimiter is "comma". You can use "or" or "none" as conjunction, and "bullet", "comma", or "semicolon" as delimiters. The `name` attribute is required to provide context for translators. **fbtee** also exports a `list` function that can be used in contexts outside of React:
-
-```tsx
-import { list } from 'fbtee';
+Pass common strings to the compiler as `fbtCommon`:
 
-const userList = list(['Alice', 'Bob', 'Charlie'], 'or', 'comma');
+```js
+{
+  fbtCommon: {
+    Save: 'Button label for saving changes',
+  },
+}
 ```
 
-### Singular & Plural Forms
+## Runtime Setup
 
-**fbtee** supports singular and plural forms using the `<fbt:plural>` component. While in English, the plural form is often just an "s" at the end of a word, in other languages, it can be more complex. **fbtee** handles this automatically based on the count value you provide. Here's an example:
+Most React apps should use `createLocaleContext`:
 
 ```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>
-```
+import { createLocaleContext } from 'fbtee';
 
-This sentence might be translated to one of the following variations:
+const availableLanguages = new Map([
+  ['en-US', 'English'],
+  ['de-DE', 'Deutsch'],
+  ['ja-JP', '日本語'],
+]);
 
-- "Do you want to play against 1 bot?"
-- "Do you want to play against 2 bots?"
+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 {};
+  }
+};
 
-`<fbt:plural>` expects the singular phrase as children, and an item `count` as prop. You can provide the plural form using the `many` prop. The `showCount` prop can be used to control whether the count should be displayed in the string. `ifMany` only shows the count in the plural case, while `yes` shows it in all cases, and `no` hides it completely. The `name` prop is required to provide context for translators.
+const LocaleContext = createLocaleContext({
+  availableLanguages,
+  clientLocales: [navigator.language, ...navigator.languages],
+  loadLocale,
+});
 
-### Using Pronouns
+export const Root = () => (
+  <LocaleContext>
+    <App />
+  </LocaleContext>
+);
+```
 
-You can use `<fbt:pronoun>` to handle pronouns in your strings. This is particularly useful for gendered languages where the pronoun changes based on the subject:
+Use `useLocaleContext` to read or change the locale:
 
 ```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>
+import { useLocaleContext } from 'fbtee';
+
+const LanguageButton = () => {
+  const { locale, setLocale } = useLocaleContext();
+  return <button onClick={() => setLocale('de-DE')}>{locale}</button>;
+};
 ```
 
-### Plain Text Usage
+If you need full control, use `setupLocaleContext` or `setupFbtee` directly.
 
-In some situations, you may want to use **fbtee** to represent plain text strings without any React components, for example when using alert dialogs or HTML attributes like `placeholder`. For these situations, you can use the `fbs()` function, which is a subset of `fbt` that only supports plain text.
+### Next.js App Router
 
-```tsx
-import { fbs } from 'fbtee';
+For App Router, put the locale context in a Client Component. If you render translated strings in Server Components, call `setupFbtee` on the server and re-render the route when the locale changes. Client-only strings can switch locale fully on the client.
 
-<input
-  type="text"
-  placeholder={fbs('Enter your name', 'Placeholder for name input')}
-/>;
-```
+See the [Next.js fbtee example](https://github.com/cpojer/nextjs-fbtee-example) for a complete setup.
 
-### Extracting Strings & Translating
+## Translation Workflow
 
-After marking your strings for translation with `<fbt>`, run the following commands to extract, and compile translations:
+Extract source strings:
 
 ```bash
 pnpm fbtee collect
 ```
 
-You can now upload the `source_strings.json` file to your translation provider, for example [Crowdin](https://crowdin.com/). If you'd like to manually edit the strings, you can use the `fbtee prepare-translations --locales de_DE` to generate a JSON file that can be edited directly. Pass `--sort-by-hash` to keep entries in a deterministic order for cleaner diffs when the file is committed.
+This writes `source_strings.json`.
 
-#### Generated File Structure
+Prepare editable translation files:
 
-Your `source_strings.json` might look like this:
-
-```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?"
-        }
-      }
-    }
-  ]
-}
+```bash
+pnpm fbtee prepare-translations --source-strings source_strings.json --output-dir translations --locales de-DE fr-FR ja-JP
 ```
 
-Based on the above source string, the US English translation (ie. `translations/en_US.json`) might look like this:
+`prepare-translations` merges source strings into existing locale files, preserves translated entries, and marks new work with `"status": "new"`. New files use BCP 47 locale identifiers by default, such as `de-DE.json` and `es-419.json`.
 
-```json
-{
-  "fb-locale": "en_US",
-  "translations": {
-    "MB6OYuvCF1VzjOmqinI42g==": {
-      "tokens": [],
-      "types": [],
-      "translations": [
-        {
-          "translation": "What's next?",
-          "variations": []
-        }
-      ]
-    }
-  }
-}
-```
-
-And German (`translations/de_DE.json`) might look like this:
-
-```json
-{
-  "fb-locale": "de_DE",
-  "translations": {
-    "MB6OYuvCF1VzjOmqinI42g==": {
-      "tokens": [],
-      "types": [],
-      "translations": [
-        {
-          "translation": "Was kommt jetzt?",
-          "variations": []
-        }
-      ]
-    }
-  }
-}
-```
-
-Once you have the translated strings stored in a `translations/` folder as JSON files using the locale name, for example `en_US.json` or `de_DE.json`, you can run the following command to generate the translations for use in your app:
+Compile translations for the app:
 
 ```bash
-pnpm fbtee translate
+pnpm fbtee translate --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations
 ```
 
-By default, **fbtee** outputs the generated translations in `src/translations`. It will create one JSON file per locale. For example, if you have `translations/en_US.json` and `translations/de_DE.json`, it will generate `src/translations/en_US.json` and `src/translations/de_DE.json`. These files are an optimized representation of your translation file, ready to be used in your app:
+fbtee accepts both modern BCP 47 locale identifiers (`de-DE`, `es-419`) and legacy Facebook-style identifiers (`de_DE`, `es_LA`). If both aliasing files exist, for example `translations/de_DE.json` and `translations/de-DE.json`, fbtee throws and asks you to keep one. Existing legacy files are updated in place; new generated files default to BCP 47. To force a specific output style, pass `--output-locale-style=bcp47`, `--output-locale-style=legacy`, or `--output-locale-style=preserve`.
 
-```json
-{
-  "de_DE": {
-    "2HVYhv": "Was kommt jetzt?"
-  }
-}
-```
+To migrate editable translation files and generated runtime files to BCP 47 names:
 
-After generating the translation files, your app is ready to display translated content in other languages. Since the `src/translations` folder is auto-generated, it should be ignored by version control and be part of your build process.
+```bash
+pnpm fbtee migrate-locales --to bcp47 --dir translations --dir src/translations
+pnpm fbtee translate --output-locale-style=bcp47
+```
 
-## Setting the initial locale
+Use `--dry-run` first to preview file renames.
 
-If you know the user's locale ahead of time, you can set it when creating the `LocaleContext` by passing the locale as the first item in the `clientLocales` array:
+Commit the human-authored translation files. Ignore generated runtime output:
 
-```tsx
-// Read the user locale from localStorage etc.
-const userLocale = localStorage.getItem('locale');
-const LocaleContext = createLocaleContext({
-  availableLanguages,
-  clientLocales: [userLocale, navigator.language, ...navigator.languages],
-  loadLocale,
-});
+```gitignore
+.enum_manifest.json
+source_strings.json
+src/translations/
 ```
 
-Note that if you are picking the locale ahead of time like this, you need to manually load the translations. This is because the `loadLocale` function is only called when the locale changes, and not when the context is first created. This gives you full control over your app's startup:
-
-```tsx
-const loadLocale = async (locale: string) => {
-  if (locale === 'ja_JP') {
-    return (await import('./translations/ja_JP.json')).default.ja_JP;
-  }
-  return {};
-};
+## Translating Strings with Coding Agents
 
-const translations = {
-  [userLocale]: await loadLocale(userLocale),
-};
+Coding agents are great at updating _fbtee_ translation files because all the context is in the repository:
 
-const LocaleContext = createLocaleContext({
-  availableLanguages,
-  clientLocales: [userLocale, navigator.language, ...navigator.languages],
-  loadLocale,
-  translations,
-});
-```
+1. `fbtee prepare-translations` adds every missing translation and marks it with `"status": "new"`.
+1. The agent edits only entries with `"status": "new"`.
+1. The agent removes `"status": "new"` after the translation is complete.
+1. Code review shows a clean diff of the new localized strings.
 
-If you have to wait for data from your server to determine the user's locale, you can use the `setLocale` function provided by `useLocaleContext` to set the locale after the initial render:
+This works best when the app already has translated strings. The agent can infer tone, voice, capitalization, punctuation, and product vocabulary from the existing locale files.
 
-```tsx
-import { useLocaleContext } from 'fbtee';
+### Coding Agent prompt:
 
-const Root = () => {
-  // Fetch the locale from the server.
-  const userLocale = useUserLocale();
-  const { locale, setLocale } = useLocaleContext();
+```md
+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.
 
-  useEffect(() => {
-    if (locale !== userLocale) {
-      setLocale(userLocale);
-    }
-  }, [locale, setLocale, userLocale]);
+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.
 
-  return children;
-};
+Remove `"status": "new"` from each completed translation entry.
 ```
 
-## ESLint Plugin
+## ESLint
 
-You can install the optional ESLint plugin to catch common mistakes and enforce best practices when using **fbtee**:
+Install the optional ESLint plugin:
 
 ```bash
 npm install -D @nkzw/eslint-plugin-fbtee
 ```
 
-Add the following configuration to your ESLint configuration:
+Use the recommended config:
 
 ```js
 import fbtee from '@nkzw/eslint-plugin-fbtee';
 
-export default [
-  fbtee.configs.recommended,
-  {
-    plugins: {
-      '@nkzw/fbtee': fbtee,
-    },
-  },
-];
-```
-
-If you want stricter enforcement of translation rules, you can use the strict configuration, which enables the `no-untranslated-strings` rule. This ensures that all strings in your codebase are marked for translation.
-
-```js
-import fbtee from '@nkzw/eslint-plugin-fbtee';
-
-export default [
-  fbtee.configs.strict,
-  {
-    plugins: {
-      '@nkzw/fbtee': fbtee,
-    },
-  },
-];
+export default [fbtee.configs.recommended];
 ```
 
-Alternatively, if you'd like more granular control over the rules:
+Use the strict config if you want every user-facing string to be wrapped:
 
 ```js
 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',
-    },
-  },
-];
+export default [fbtee.configs.strict];
 ```
 
-## What's better about `fbtee` than `fbt`?
-
-Facebook has done an amazing job with `fbt`, an internationalization library that has been successfully used in production at Facebook for over 10 years. Their work provided a strong foundation for modern localization tools.
-
-The open-source version of `fbt`, however, became unmaintained, difficult to set up, and incompatible with modern tools. It was eventually archived in November 2024. **fbtee** builds on this foundation with several improvements:
-
-- **Easier Setup:** fbtee works with modern tools like Vite.
-- **Statically Typed:** The fbtee compiler ensures correct usage of fbtee, library TypeScript types are provided, and an eslint plugin helps fix common mistakes.
-- **Improved React Compatibility:** Removed React-specific hacks and added support for implicit React fragments (`<>`).
-- **Enhanced Features:** Fixed and exported `intlList` as a new `<fbt:list>` construct, which was not functional in the original `fbt`.
-- **Modernized Codebase:** Rewritten using TypeScript, ES modules (ESM), eslint, and modern JavaScript standards. Removed cruft and legacy code.
-- **Updated Tooling:** Uses modern tools like pnpm, Vite, and esbuild for faster and more efficient development of **fbtee**.
-
-**fbtee** remains compatible with `fbt` and migration is straightforward.
+## Migration from fbt
 
-## Migration from `fbt`
+_fbtee_ is compatible with the core `fbt` programming model:
 
-**fbtee** is compatible with `fbt`. If you are already using `fbt`, migrating to fbtee is straightforward:
+1. Replace `fbt` packages with `fbtee` and the matching compiler package.
+1. Replace imports from `fbt` with imports from `fbtee`.
+1. Use `fbtee collect`, `fbtee prepare-translations`, and `fbtee translate`.
+1. Convert CommonJS common strings or enum modules to ESM when needed.
+1. Replace legacy setup calls with `setupFbtee`, `createLocaleContext`, or `setupLocaleContext`.
 
-- Follow the "Getting Started" guide above and remove all "fbt" related packages.
-- Make sure you are using React 19.
-- Replace `import { fbt } from 'fbt'` with `import { fbt } from 'fbtee'`.
-- Rename commands from `fbt-collect`, and `fbt-translate` to `fbtee-collect`, and `fbtee-translate`. `fbt manifest` was removed and `fbtee collect` now handles this step automatically.
-- If you were using CommonJS modules for common strings or enums, convert them to ES modules.
-- Ensure you are using the latest version of Node.js 22 or later.
-- Rename your `init({})` call to `setupFbtee({})`.
+Some archived `fbt` options and legacy behaviors were intentionally removed. The compiler errors should point to the modern replacement when one exists.
 
-After these changes, your project should work seamlessly with **fbtee**.
+## Examples
 
-_Note: Some legacy behavior and options were removed from `fbtee`. If you have a complex setup, please consider [reaching out to us for help](mailto:fbtee@nakazawa.dev)._
+- [Example App](https://github.com/nkzw-tech/fbtee/tree/main/example)
+- [Next.js App Router Example](https://github.com/cpojer/nextjs-fbtee-example)
+- [Athena Crisis](https://github.com/nkzw-tech/athena-crisis)
 
 ## Credits
 
 - `fbt` was originally created by [Facebook](https://github.com/facebook/fbt).
 - The auto-import plugin was created by [@alexandernanberg](https://github.com/alexandernanberg).
-- [Nakazawa Tech](https://nkzw.tech) rewrote `fbt` into `fbtee` and continues to maintain this project.
+- [Nakazawa Tech](https://nkzw.tech) rewrote `fbt` into _fbtee_ and maintains this project.

package/lib/index.mjs

@@ -1,7 +1,7 @@
 import { ESLintUtils } from "@typescript-eslint/utils";
 //#region package.json
 var name = "@nkzw/eslint-plugin-fbtee";
-var version = "1.8.0";
+var version = "2.0.0";
 //#endregion
 //#region src/utils.tsx
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/${name}.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/eslint-plugin-fbtee",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "",
   "keywords": [],
   "repository": {