Add createFixedFbt and FixedLocaleContext for locale-fixed translations

[bk-tho]

Disclaimer: This was written entirely by Opus 4.6 High. I believe I guided it thoroughly into the right direction. I reviewed and tested the result myself.

Summary

Adds locale-fixed translation support for fbtee — the equivalent of i18next's getFixedT. Two complementary APIs:

1. <FixedLocaleContext> — React (transparent)

A context provider that transparently overrides the locale for all <fbt>, fbt(), <fbs>, and fbs() calls in descendant components. No call-site changes needed in children.

import { fbt, FixedLocaleContext } from "fbtee";

function App() {
  return (
    <div>
      <h1><fbt desc="title">Hello World</fbt></h1>
      <Suspense fallback="Loading...">
        <FixedLocaleContext locale="de_DE">
          <GermanPreview />
        </FixedLocaleContext>
      </Suspense>
    </div>
  );
}

function GermanPreview() {
  return <p><fbt desc="greeting">Hello World</fbt></p>;
}

On-demand translation loading: If translations for the requested locale are not yet loaded and a loadLocale hook has been registered (via setupLocaleContext), FixedLocaleContext will suspend until translations are fetched. Wrap in <Suspense> to handle the loading state. Already-loaded locales render immediately.

Note: Like all React context providers, the override only affects child components, not fbt/fbs calls in the same component that renders <FixedLocaleContext>.

2. createFixedFbt(locale, gender?) — Non-React (programmatic)

Returns { fbt, fbs } runtimes bound to a specific locale. Shadow the global fbt/fbs binding and the babel plugin compiles calls normally:

import { createFixedFbt } from "fbtee";
const { fbt } = createFixedFbt("de_DE");

const greeting = fbt("Hello", "greeting"); // → "Hallo"

How it works

Babel plugin

The plugin detects React components (/^[A-Z]/), hooks (/^use[A-Z0-9]/), and React.forwardRef/React.memo callbacks that contain fbt._() or fbs._() calls. For these functions, it:

1. Injects const __fbtLocaleOverride = fbt.__locale?.() ?? null; at the top
2. Passes __fbtLocaleOverride as 4th argument to all fbt._() / fbs._() calls

Non-component functions are left unchanged (use global locale).

Runtime

• fbt.__locale() reads from FbtLocaleOverrideContext via a registered hook
• fbt._() checks the 4th argument: if present, delegates to the fixed runtime; otherwise uses global hooks as before
• <FixedLocaleContext> provides the fixed runtime (created by createFixedFbt) via React context
• On-demand loading: if translations are missing, uses the registered loadLocale hook + React use() to suspend until loaded, then merges into FbtTranslations
• createFixedFbt creates isolated runtimes with their own getTranslatedInput and getViewerContext

Backward compatibility

Scenario	Behavior
Old plugin + new runtime	fbt._() with 3 args → 4th is undefined → global hooks
New plugin + old runtime	fbt._() with 4 args → extra arg ignored by JS
No <FixedLocaleContext> in tree	__locale?.() returns null → global hooks
FixedLocaleContext not imported	Hook never registered → null

Changes

packages/babel-plugin-fbtee/

• src/index.tsx — injectLocaleOverrides() in Program.exit: component/hook detection + hook injection + 4th arg addition

packages/fbtee/

• src/fbt.tsx — FbtLocaleOverride type, __locale() method, localeOverride 4th param on _(), runtimeKey param on createRuntime
• src/fbs.tsx — runtimeKey: "fbs"
• src/Hooks.tsx — LoadLocaleFn type, loadLocale in Hooks, getLoadLocale(), getLocaleOverrideHook() / setLocaleOverrideHook()
• src/setupLocaleContext.tsx — Registers loadLocale in hooks during setup
• src/FixedLocaleContext.tsx — New: React context provider with on-demand translation loading via useEnsureLocaleLoaded + Suspense
• src/createFixedFbt.tsx — New: isolated runtime factory
• src/index-server.tsx — Exports createFixedFbt and FixedLocaleContext

example/

• fixedLocale.html + src/fixedLocale.tsx + src/example/FixedLocaleDemo.tsx — Comprehensive demo page with on-demand loading (1s simulated delay), Suspense fallbacks, all test cases
• src/example/Example.tsx — Multi-Locale Preview section

Tests

• 13 babel plugin tests (component detection, hook detection, non-component exclusion, fbs, forwardRef/memo, 4th arg)
• 6 runtime FixedLocaleContext tests (fixed locale, isolation, nesting, global unaffected, fbs, async loading with Suspense)
• 7 runtime createFixedFbt tests (locale, fbs, fallback, gender, concurrency, late registration)