@nkzw/vite-plugin-fbtee 3.3.0 → 5.0.0

package/README.md

@@ -10,132 +10,92 @@ const Greeting = ({ name }) => (
 );
 ```
 
-_fbtee_ is a modern continuation of Facebook's `fbt`, rebuilt for TypeScript, ESM, React 19, Vite, Next.js, Babel & Oxc.
+_fbtee_ is a modern continuation of Facebook's `fbt`, rebuilt for TypeScript, ESM, React 19, Vite, Next.js, and Oxc.
 
 ## 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, 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 Vite, Next.js, Babel, Oxc, and Expo.
+- **Easy Setup:** Quick integration with Vite, Next.js, Oxc, and Expo.
 
 ## Getting Started
 
-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)
-
-For an existing app, install the runtime:
+For a new project, start with the [fate stack](https://stack.fate.technology) or the [Expo template](https://github.com/nkzw-tech/expo-app-template). For an existing app, install the fbtee runtime and compiler:
 
 ```bash
 npm install fbtee
+npm install -D @nkzw/fbtee-compiler
 ```
 
-_fbtee_ requires Node 22+. React apps should use React 19+.
+The compiler package includes the `fbtee` command and the JavaScript compiler API. Keep it in `devDependencies`; applications use `fbtee` at runtime.
 
-### Vite
+The toolchain requires Node 22.12+. React apps require React 19+.
 
-Most projects should install the ready-to-use Vite plugin and the CLI:
+### Vite
 
 ```bash
-npm install -D @nkzw/vite-plugin-fbtee @nkzw/fbtee-cli
+npm install -D @nkzw/vite-plugin-fbtee
 ```
 
-Add the fbtee plugin before the React plugin:
+Place fbtee before the React plugin:
 
-```js
+```ts
 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(),
-  ],
+  plugins: [fbtee(), react()],
 });
 ```
 
 ### Next.js
 
-Next.js projects should use the native Oxc plugin and the CLI:
-
 ```bash
-npm install -D @nkzw/next-plugin-fbtee @nkzw/fbtee-cli
+npm install -D @nkzw/next-plugin-fbtee
 ```
 
-Wrap your Next configuration:
-
-```js
+```ts
 import withFbtee from '@nkzw/next-plugin-fbtee';
 
-export default withFbtee({
-  fbtCommon: {
-    Accept: 'Button label for accepting terms',
-  },
-  fbtEnumManifest: {},
-})({
-  // Your Next.js configuration.
-});
+export default withFbtee()({});
 ```
 
-The plugin runs the native Oxc transform before Next.js compilation. It works with the default Turbopack compiler and with `next build --webpack`, so it does not require Babel or custom compiler configuration.
+The plugin supports Turbopack and Webpack.
 
-### Babel
+<details>
+<summary>Custom builds with Oxc</summary>
 
-Install the Babel preset and the CLI:
+Run the fbtee transform before lowering TypeScript and JSX:
 
 ```bash
-npm install -D @nkzw/babel-preset-fbtee @nkzw/fbtee-cli
+npm install -D @nkzw/fbtee-compiler oxc-transform
 ```
 
-Add the preset to your Babel configuration:
-
-```js
-export default {
-  presets: ['@nkzw/babel-preset-fbtee'],
-};
-```
-
-### Low-level Oxc Transform
-
-For custom build-system integrations, install the native Oxc transform:
-
-```bash
-npm install -D @nkzw/oxc-transform-fbtee @nkzw/fbtee-cli oxc-transform
-```
-
-Apply the fbtee transform before the standard Oxc transform:
-
-```js
-import { transformSync as transformFbtee } from '@nkzw/oxc-transform-fbtee';
+```ts
+import { transformSync as transformFbtee } from '@nkzw/fbtee-compiler';
 import { transformSync as transformOxc } from 'oxc-transform';
 
-const fbteeResult = transformFbtee(filename, sourceText, {
-  fbtCommon: {
-    Accept: 'Button label for accepting terms',
-  },
-  fbtEnumManifest: {},
-});
+export function compile(filename: string, source: string) {
+  const translated = transformFbtee(filename, source);
+  if (translated.errors.length) {
+    throw new Error(translated.errors.map(({ message }) => message).join('\n'));
+  }
 
-if (fbteeResult.errors.length > 0) {
-  throw new Error(fbteeResult.errors.map(({ message }) => message).join('\n'));
+  return transformOxc(filename, translated.code, {
+    jsx: { runtime: 'automatic' },
+  });
 }
-
-const result = transformOxc(filename, fbteeResult.code, {
-  jsx: { runtime: 'automatic' },
-});
 ```
 
-### TypeScript JSX Types
+The returned Oxc result contains the generated code and any downstream errors. See the [transform options](https://github.com/nkzw-tech/fbtee/blob/main/packages/fbtee-compiler/index.d.ts) for common strings and enum configuration.
 
-React TypeScript projects should include the JSX declarations once in a global type file or app entry point:
+</details>
+
+### TypeScript
+
+Add the JSX declarations to a global type file or your app entry point:
 
 ```tsx
 /// <reference types="fbtee/ReactTypes.d.ts" />
@@ -143,31 +103,25 @@ React TypeScript projects should include the JSX declarations once in a global t
 
 ## Writing Strings
 
-Every user-facing string should be wrapped in `<fbt>`, `fbt()`, or `fbs()`. Descriptions are required because they are the translator's context.
+Wrap a sentence in `<fbt>` and describe where it appears. The description helps translators choose the right words:
 
 ```tsx
-<fbt desc="Empty state title when a project has no tasks">No tasks yet</fbt>
+<fbt desc="Empty state when a project has no tasks">No tasks yet</fbt>
 ```
 
-Use `fbt()` outside JSX:
+The compiler supplies the global `fbt` import for JSX. Use `fbt()` in JavaScript, or `fbs()` where an API requires a plain string:
 
 ```tsx
-import { fbt } from 'fbtee';
+import { fbs, fbt } from 'fbtee';
 
-const title = fbt('No tasks yet', 'Empty state title when a project has no tasks');
-```
+const title = fbt('No tasks yet', 'Empty state when a project has no tasks');
 
-Use `fbs()` when you need a plain string:
-
-```tsx
-import { fbs } from 'fbtee';
-
-<input placeholder={fbs('Search projects', 'Project search input placeholder')} />;
+<input placeholder={fbs('Search projects', 'Project search placeholder')} />;
 ```
 
-## Dynamic Content
+### Dynamic Content
 
-Use `<fbt:param>` for dynamic values. Token names should describe the value, not its current English position.
+Give dynamic values meaningful names with `<fbt:param>`. React elements inside a sentence become parameters automatically, as in the greeting above.
 
 ```tsx
 <fbt desc="Greeting with the viewer name">
@@ -175,255 +129,281 @@ Use `<fbt:param>` for dynamic values. Token names should describe the value, not
 </fbt>
 ```
 
-React elements inside `<fbt>` are automatically turned into implicit params:
-
-```tsx
-<fbt desc="Greeting with a linked viewer name">
-  Hello, <UserLink user={viewer} />!
-</fbt>
-```
-
-Use `fbt.sameParam()` or `<fbt:same-param>` when the same token appears more than once.
+For repeated values, use `<fbt:same-param>` or `fbt.sameParam()`.
 
-## Plurals
+### Plurals and Lists
 
-Use `<fbt:plural>` when a count controls grammar. _fbtee_ handles locale-specific plural rules.
+Describe the singular and plural forms in your source language. fbtee selects the translated form for the locale:
 
 ```tsx
 <fbt desc="Inbox unread count">
   You have{' '}
-  <fbt:plural count={count} many="unread messages" name="unreadCount" showCount="yes">
-    an unread message
-  </fbt:plural>
-  .
+  <fbt:plural count={count} many="unread messages" name="count" showCount="yes">
+    unread message
+  </fbt:plural>.
 </fbt>
 ```
 
-`showCount` can be `yes`, `ifMany`, or `no`.
-
-## Lists
-
-Use `<fbt:list>` for locale-aware lists:
+`showCount` accepts `yes`, `ifMany`, or `no`. For lists, use `<fbt:list>` or the standalone `list()` helper:
 
 ```tsx
 <fbt desc="People assigned to a task">
-  Assigned to <fbt:list items={assignees} name="assigneeList" />.
+  Assigned to <fbt:list items={assignees} name="assignees" />.
 </fbt>
 ```
 
-The standalone `list()` helper is available for non-React code:
+fbtee also supports enums, gender, and pronouns. See the [website examples](https://fbtee.dev) for each.
 
-```tsx
-import { list } from 'fbtee';
+### Common Strings
 
-const names = list(['Alice', 'Bob', 'Charlie'], 'or', 'comma');
-```
+Share a description for labels that mean the same thing throughout the app. Define them in `common_strings.json`:
 
-## Enums
+```json
+{
+  "Save": "Button label for saving changes"
+}
+```
 
-Use enums when runtime values map to a fixed set of translatable labels:
+Pass this object as `fbtCommon` to your compiler plugin and add `--common common_strings.json` when collecting strings. Then use the label without repeating its description:
 
 ```tsx
-const StatusLabels = {
-  done: 'done',
-  open: 'open',
-};
-
-<fbt desc="Task status label">
-  This task is <fbt:enum enum-range={StatusLabels} value={status} />.
-</fbt>;
+<fbt common>Save</fbt>
 ```
 
-For shared enum modules, use the `$FbtEnum` suffix so the collector can resolve them.
+## Translation Workflow
 
-## Pronouns and Gender
+First, extract the strings and prepare a file for each language:
 
-Use `<fbt:pronoun>` when a phrase depends on a person's gender:
+```bash
+npx fbtee collect
+npx fbtee prepare-translations --source-strings source_strings.json --output-dir translations --locales de-DE ja-JP
+```
 
-```tsx
-<fbt desc="Photo sharing notification">
-  <fbt:param name="name">{user.name}</fbt:param> shared{' '}
-  <fbt:pronoun gender={user.gender} human type="possessive" /> photo.
-</fbt>
+Translate the entries marked `"status": "new"`, then remove that status. Existing translations are preserved when you run the command again. Compile the files for your app:
+
+```bash
+npx fbtee translate --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations
 ```
 
-Supported pronoun types are `subject`, `object`, `possessive`, and `reflexive`.
+Generated runtime catalogs omit messages with no completed translation, including entries still marked `"status": "new"`. This lets partial catalogs fall back to another language. After upgrading, recompile existing catalogs to enable this behavior. Explicit translations equal to the source text are preserved. Fallback applies to whole messages; a partially translated plural/gender table keeps its existing within-message fallback behavior.
 
-## Common Strings
+Use `fbtee translate --strict` to require a completed entry for every collected source hash in each supplied locale. Missing entries, entries marked `"status": "new"`, and empty translation lists fail before output is written. Explicit empty-string translations and translations equal to the source remain valid.
 
-Common strings are reusable source strings with shared descriptions:
+Commit the editable files in `translations/`. Add generated files to `.gitignore`:
 
-```tsx
-<fbt common>Save</fbt>
+```gitignore
+.enum_manifest.json
+source_strings.json
+src/translations/
 ```
 
-Pass common strings to the compiler as `fbtCommon`:
+The npm package includes a [translation skill](https://github.com/nkzw-tech/fbtee/blob/main/packages/fbtee/skills/fbtee-translate/SKILL.md) for coding agents. It prepares translations, fills every new entry across the supported locales, and uses existing translations and source-code context to match terminology and tone. To use it, ask your agent:
 
-```js
-{
-  fbtCommon: {
-    Save: 'Button label for saving changes',
-  },
-}
+```text
+Read node_modules/fbtee/skills/fbtee-translate/SKILL.md and translate all new strings for all supported locales.
 ```
 
+Review the resulting diff as you would any translation.
+
 ## Runtime Setup
 
-Most React apps should use `createLocaleContext`:
+For an app with one active language, use `createLocaleContext`. It selects a supported locale from the browser's preferences and loads translations when the language changes.
 
 ```tsx
 import { createLocaleContext } from 'fbtee';
-
-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 {};
-  }
-};
+import { createRoot } from 'react-dom/client';
+import App from './App.tsx';
 
 const LocaleContext = createLocaleContext({
-  availableLanguages,
-  clientLocales: [navigator.language, ...navigator.languages],
-  loadLocale,
+  availableLanguages: new Map([
+    ['en-US', 'English'],
+    ['de-DE', 'Deutsch'],
+  ]),
+  clientLocales: navigator.languages,
+  loadLocale: async (locale) =>
+    locale === 'de-DE' ? (await import('./translations/de-DE.json')).default['de-DE'] : {},
 });
 
-export const Root = () => (
+await LocaleContext.preload();
+
+createRoot(document.getElementById('root')!).render(
   <LocaleContext>
     <App />
-  </LocaleContext>
+  </LocaleContext>,
 );
 ```
 
-Use `useLocaleContext` to read or change the locale:
+Call `preload()` once before rendering to load the initial language and its available fallback catalogs. Creating the context does not load them automatically. You can skip preloading if you supply all those catalogs at setup; the source locale does not require a catalog.
+
+Preloading and language changes share pending loads. Loading failures reject the promise; calling again retries them.
+
+Use `useLocaleContext()` to change the language in a React transition:
 
 ```tsx
 import { useLocaleContext } from 'fbtee';
+import { useTransition } from 'react';
 
-const LanguageButton = () => {
+function LanguageButton() {
   const { locale, setLocale } = useLocaleContext();
-  return <button onClick={() => setLocale('de-DE')}>{locale}</button>;
-};
-```
+  const [, startTransition] = useTransition();
 
-If you need full control, use `setupLocaleContext` or `setupFbtee` directly.
+  return <button onClick={() => startTransition(() => setLocale('de-DE'))}>{locale}</button>;
+}
+```
 
-### Next.js App Router
+Outside React, use `setupLocaleContext` and await `preloadLocale()`, or configure the runtime directly with `setupFbtee`.
 
-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.
+### Formatting Numbers and Dates
 
-See the [Next.js fbtee example](https://github.com/cpojer/nextjs-fbtee-example) for a complete setup.
+Use JavaScript's native `Intl` APIs for numbers, currencies, dates, times, and relative time. Pass fbtee's active locale to the formatter and insert the result with `<fbt:param>`:
 
-## Translation Workflow
+```tsx
+import { useLocaleContext } from 'fbtee';
 
-Every CLI command can use the native Oxc/Rust pipeline by adding `--oxc`:
+function Price({ amount, currency }: { amount: number; currency: string }) {
+  const { locale } = useLocaleContext();
+  const price = new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);
 
-```bash
-pnpm fbtee collect --oxc
-pnpm fbtee prepare-translations --oxc --source-strings source_strings.json --output-dir translations
-pnpm fbtee translate --oxc --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations
-pnpm fbtee migrate-locales --oxc --to bcp47 --dir translations --dir src/translations
+  return (
+    <fbt desc="Product price">
+      Price: <fbt:param name="price">{price}</fbt:param>
+    </fbt>
+  );
+}
 ```
 
-The Babel pipeline remains the default during the parity rollout, so removing `--oxc` makes it easy to compare both implementations. Successful native outputs are tested byte-for-byte against Babel. The native collector intentionally cannot execute Babel-specific JavaScript extensions: `--custom-collector`, `--transform`, and `--generate-fbt-nodes` are unavailable with `--oxc`.
+With scoped runtimes, use the `locale` returned by `useFbt()`. Reuse formatter instances when formatting many values with the same locale and options. For server-rendered dates and relative times, keep the locale, time zone, and reference time consistent between server and client; these settings belong to your application.
 
-The Oxc collector also cannot run plugins or presets from a Babel configuration file or apply `.babelignore`. If it detects Babel configuration or ignore rules, it stops instead of silently collecting different source. Use the Babel collector when that preprocessing is required, or pass `--disable-babel-config` to explicitly collect the unmodified source with Oxc. All other documented options are supported.
+### Locale Matching and Fallback
 
-Extract source strings:
+Fallback works automatically for each message: `fr-CA` checks its Canadian French catalog, then `fr`, then the source locale's catalog if supplied, and finally the inline source text. A translated regional message always wins. An empty string counts as a translation.
 
-```bash
-pnpm fbtee collect
-```
+To use a shared French catalog, include `fr` alongside `fr-CA` in `availableLanguages` and return each catalog from `loadLocale`. `preload()` and language changes load the available fallback catalogs in parallel, share pending loads, and retry failed loads. A supplied `fr` catalog does not prevent loading `fr-CA`. With `setupFbtee`, `createFbteeRuntime`, or `runWithFbtee`, supply the fallback catalogs in `translations`.
 
-This writes `source_strings.json`.
+Matching accepts BCP 47 and legacy identifiers such as `fr-CA` and `fr_CA`. It prefers exact locales, then language/script parents. If none are available during language selection, it chooses a region with the same language and script, preferring the region inferred by `Intl.Locale` and using a stable order for ties. Catalog insertion order does not determine the selected language. Traditional Chinese falls back through `zh-Hant`; it does not automatically use a Simplified Chinese catalog. Per-message fallback does not choose arbitrary sibling regions.
 
-Prepare editable translation files:
+Most apps need no additional settings. All setup APIs accept these optional settings:
 
-```bash
-pnpm fbtee prepare-translations --source-strings source_strings.json --output-dir translations --locales de-DE fr-FR ja-JP
+```tsx
+const runtime = createFbteeRuntime({
+  locale: 'fr-CA',
+  translations,
+  sourceLocale: 'en-US', // Default; change this for non-English inline messages.
+  fallbackLocales: {
+    'fr-CA': ['fr-FR'], // After natural parents, before the source locale.
+    default: ['en-GB'], // Additional fallbacks for every locale.
+  },
+  onMissingTranslation: ({ locale, hashKey, sourceLocale }) => {
+    reportMissingTranslation({ locale, hashKey, sourceLocale });
+  },
+});
 ```
 
-`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`.
+`fallbackLocales` also accepts an array, such as `['fr', 'en-GB']`, for every locale. Mappings can refer to other mapped locales; cycles and duplicate catalogs are ignored. Plural selection and phonological rewrites follow the language of the catalog supplying the message, or `sourceLocale` for inline source text; interpolated numbers retain the viewer's number formatting.
 
-Compile translations for the app:
+`onMissingTranslation` runs only when no catalog in the chain contains the message and inline source text is used. It reports each locale/message once per runtime, resets when translations are registered or merged, and does not report normal source-locale rendering. No generic missing-catalog warning is emitted. Custom `hooks.getTranslatedInput` implementations remain responsible for their own fallback and reporting. They can return `locale` alongside `args` and `table` to select the message's phonological rewrites; omitting it preserves the viewer locale.
 
-```bash
-pnpm fbtee translate --source-strings source_strings.json --translations 'translations/*.json' --output-dir src/translations
-```
+For locale contexts, `fallbackLocale` controls the selected language when none of `clientLocales` is supported. It defaults to `sourceLocale`. Use `fallbackLocales` to configure per-message fallback, and set `sourceLocale` when the inline messages are not US English.
 
-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`.
+### Scoped Runtimes
 
-To migrate editable translation files and generated runtime files to BCP 47 names:
+Use `LocaleProvider` when part of a page needs its own language. Create a runtime with its translations, then call `useFbt()` in the components that translate:
 
-```bash
-pnpm fbtee migrate-locales --to bcp47 --dir translations --dir src/translations
-pnpm fbtee translate --output-locale-style=bcp47
-```
+```tsx
+import { createFbteeRuntime, LocaleProvider, useFbt } from 'fbtee';
+import german from './translations/de-DE.json' with { type: 'json' };
 
-Use `--dry-run` first to preview file renames.
+const germanRuntime = createFbteeRuntime({ locale: 'de-DE', translations: german });
 
-Commit the human-authored translation files. Ignore generated runtime output:
+function SaveButton() {
+  const { fbt } = useFbt();
+  return <button>{fbt('Save', 'Save button')}</button>;
+}
 
-```gitignore
-.enum_manifest.json
-source_strings.json
-src/translations/
+function Preview() {
+  return (
+    <LocaleProvider runtime={germanRuntime}>
+      <SaveButton />
+    </LocaleProvider>
+  );
+}
 ```
 
-## Translating Strings with Coding Agents
+Create runtimes once, outside rendering or with React state. Each translating component calls `useFbt()`, which requires a provider and also returns `fbs`, `list`, and `locale`. Nested providers and separate roots can use different runtimes. Global imports keep their existing behavior.
 
-Coding agents are great at updating _fbtee_ translation files because all the context is in the repository:
+A runtime's locale and gender are fixed; switch the provider's runtime to change them. Async actions keep the translator they captured, even across `await`. Pass it explicitly to helpers in other modules:
+
+```tsx
+import type { FbtAPI } from 'fbtee';
+
+export async function saveMessage(fbt: FbtAPI) {
+  await saveDocument();
+  return fbt('Saved', 'Save confirmation');
+}
+```
 
-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.
+Keep the local names `fbt` and `fbs`. For helper arguments and imported runtimes, annotate with the imported `FbtAPI`, `FbsAPI`, or `FbteeRuntime` type so the compiler recognizes them. If a linter reports a JSX-only translator as unused, keep the binding and suppress the warning or use the function form.
 
-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.
+Load more translations with `germanRuntime.mergeTranslations(bundle)`, using compiled bundles shaped as `{ locale: { hash: translation } }`. Mounted consumers update automatically. Load before displaying the relevant UI to avoid briefly showing source strings.
 
-### Coding Agent prompt:
+### Server Rendering
 
-```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.
+In Node.js, wrap the render in `runWithFbtee` to give each request its own locale. Imported `fbt`, `fbs`, and `list` calls use that scope, including across asynchronous work:
 
-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.
+```tsx
+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' };
 
-Remove `"status": "new"` from each completed translation entry.
+export function renderPage() {
+  return runWithFbtee({ locale: 'de-DE', translations: german }, () => renderToString(<App />));
+}
 ```
 
-## ESLint
+Start the actual renderer inside the callback, including for streaming SSR. Wrapping a component's JSX return does not scope its descendants. Load translations before rendering, and use the same locale and translations for client hydration.
+
+Each request has its own hooks and caches. Calls to `setupFbtee` and `FbtTranslations` inside the callback affect only that scope; nested scopes start with their own configuration. Promises, timers, and Suspense retries created inside it retain the scope. Use Node's `AsyncLocalStorage.bind()` for callbacks handed to an external scheduler.
+
+The Next.js plugin handles compilation, not request isolation. Use `runWithFbtee` where you control the renderer or in Node route handlers. Server Components can use explicit runtimes; `LocaleProvider` and `useFbt()` belong in Client Components. Pass locale and translation data across that boundary, since runtime objects contain functions. Server-rendered translations need a new server render when the language changes.
+
+### Shared Translations
+
+Scoped runtimes and requests share catalogs by reference. Treat them as read-only: use `runtime.mergeTranslations()` or, inside a request, `FbtTranslations.mergeTranslations()` and `registerTranslations()` for updates. Merges copy affected locale maps while sharing nested tables. Scoped catalogs are frozen automatically in development and tests; production registration does not freeze or copy them. Ordinary singleton catalogs remain mutable.
+
+## Linting
 
-Install the optional ESLint plugin:
+The optional ESLint plugin checks strings and translator descriptions:
 
 ```bash
 npm install -D @nkzw/eslint-plugin-fbtee
 ```
 
-Use the recommended config:
-
 ```js
 import fbtee from '@nkzw/eslint-plugin-fbtee';
 
-export default [fbtee.configs.recommended];
+export default [
+  {
+    plugins: { '@nkzw/fbtee': fbtee },
+    rules: fbtee.configs.recommended.rules,
+  },
+];
 ```
 
-Use the strict config if you want every user-facing string to be wrapped:
+Use `fbtee.configs.strict.rules` to also check for untranslated text.
 
-```js
-import fbtee from '@nkzw/eslint-plugin-fbtee';
+## Migration from fbtee 4
 
-export default [fbtee.configs.strict];
+fbtee 5 combines `@nkzw/fbtee-cli` and `@nkzw/oxc-transform-fbtee` into `@nkzw/fbtee-compiler`:
+
+```sh
+npm uninstall @nkzw/fbtee-cli @nkzw/oxc-transform-fbtee
+npm install fbtee@^5
+npm install -D @nkzw/fbtee-compiler@^5
 ```
 
+Update any installed fbtee Vite, Next.js, and ESLint plugins to v5. For custom compiler integrations, replace imports from `@nkzw/oxc-transform-fbtee` with `@nkzw/fbtee-compiler`. The compiler API and existing `fbtee` commands are unchanged. Runtime imports continue to use `fbtee`.
+
 ## Migration from fbt
 
 _fbtee_ is compatible with the core `fbt` programming model:
@@ -436,14 +416,14 @@ _fbtee_ is compatible with the core `fbt` programming model:
 
 Some archived `fbt` options and legacy behaviors were intentionally removed. The compiler errors should point to the modern replacement when one exists.
 
-## Examples
+fbtee uses Oxc and a native CLI. Replace the Babel integration with the Vite or Next.js plugin above, or use `@nkzw/fbtee-compiler` directly. Babel-specific extensions (`--custom-collector`, `--transform`, `--generate-fbt-nodes`, and `--hash-module`) are no longer supported. The collector cannot execute Babel configuration or apply `.babelignore`; remove that legacy configuration, or use `--disable-babel-config` to collect unmodified source.
+
+Both `de-DE` and legacy locale names such as `de_DE` work. To rename catalogs, run `npx fbtee migrate-locales --to bcp47 --dir translations --dir src/translations --dry-run`, then repeat without `--dry-run`. Keep one file per locale; new files use BCP 47 names by default.
 
-- [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)
+## Examples and Credits
 
-## Credits
+- [Example app](https://github.com/nkzw-tech/fbtee/tree/main/example), including independent locale widgets.
+- [Next.js example](https://github.com/cpojer/nextjs-fbtee-example).
+- [Athena Crisis](https://github.com/nkzw-tech/athena-crisis).
 
-- `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 maintains this project.
+Originally created as [`fbt` at Facebook](https://github.com/facebook/fbt), with auto-import support by [@alexandernanberg](https://github.com/alexandernanberg). Rebuilt and maintained as fbtee by [Nakazawa Tech](https://nkzw.tech).

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { TransformOptions } from '@nkzw/oxc-transform-fbtee';
+import type { TransformOptions } from '@nkzw/fbtee-compiler';
 import type { Plugin } from 'vite';
 
 export type FbteeVitePluginOptions = Omit<TransformOptions, 'lang' | 'sourcemap' | 'sourceType'>;

package/index.js

@@ -1,4 +1,4 @@
-import { transformSync } from '@nkzw/oxc-transform-fbtee';
+import { transformSync } from '@nkzw/fbtee-compiler';
 
 const fbteeSourcePattern = /fbt|fbs/;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/vite-plugin-fbtee",
-  "version": "3.3.0",
+  "version": "5.0.0",
   "description": "Vite plugin for fbtee powered by the native Oxc transform.",
   "keywords": [
     "fbt",
@@ -33,7 +33,7 @@
     }
   },
   "dependencies": {
-    "@nkzw/oxc-transform-fbtee": "3.3.0"
+    "@nkzw/fbtee-compiler": "5.0.0"
   },
   "devDependencies": {
     "vite": "^8.1.5"