Internationalization (i18n)

How It Works

Translations are written inline using the t() function. A Babel plugin transforms these calls at compile time into hash-based lookups against generated JSON bundles. The same t() API works in both server and client components — the Babel plugin selects the correct runtime automatically.

Source: t({ en: "Hello", zh: "你好" })
  ↓ Babel plugin
Server: __i18n_lookup("a8cfb50c")                — reads from server JSON bundle
Client: i18nLookup(_translations, "a8cfb50c")   — reads the translations that
        const _translations = useI18nTranslations() reads from React context
        at the top of the enclosing component or hook

Supported Locales

• en — English
• zh — Chinese

Defined as SupportedLocale in apps/web/src/i18n/types.ts. Pages live under apps/web/src/app/[locale]/. en is the default and has no URL prefix (/design-system); zh has one (/zh/design-system).

The t() Function

Import from #src/i18n.ts. Pass an object with en and zh string literal properties:

import { t } from "#src/i18n.ts";

// Plain text
t({ en: "Hello", zh: "你好" });

// With HTML markup — returns ReactNode instead of string
t(
  { en: "<strong>Bold text</strong>", zh: "<strong>粗体文字</strong>" },
  { parse: true },
);

Both en and zh values must be string literals — no variables, template literals, or expressions. The codegen and Babel plugin rely on statically extracting these at build time.

Supported HTML tags in { parse: true } mode: <strong>, <em>, <b>, <i>, <p>.

Server Components

Use t() directly. No special setup needed — the Babel plugin handles everything:

import { t } from "#src/i18n.ts";

export default function Page() {
  return <h1>{t({ en: "Welcome", zh: "欢迎" })}</h1>;
}

For page files (page.tsx under [locale]), the Babel plugin auto-injects setLocale() at the top of the default export function. You do not need to manually call setLocale or accept params — the plugin makes the function async, reads params.locale, and calls setLocale(validateLocale(params.locale)) for you. It does the same for an exported generateMetadata in page and layout files.

Layout files that need the locale for other purposes (e.g. generateMetadata, routing logic) should still read params manually since they have non-i18n reasons to do so.

Client Components

Use t() identically — the Babel plugin detects "use client" and swaps in client-specific lookup functions that read from React context:

"use client";

import { t } from "#src/i18n.ts";

export function SearchButton() {
  return <button>{t({ en: "Search", zh: "搜索" })}</button>;
}

Client translations are provided automatically. The codegen generates a manifest mapping page/layout files to their client translation bundles. The Babel plugin reads this manifest and auto-wraps the default export's return value with <ClientTranslationsProvider>, so client components receive translations without any manual wiring.

Getting the Locale in Client Components

Use the useLocale() hook when you need the locale value itself (not for translations):

"use client";

import { useLocale } from "#src/i18n/use-locale.ts";

export function LocaleAwareComponent() {
  const locale = useLocale();
  const formatter = new Intl.NumberFormat(locale);
  return <span>{formatter.format(1234)}</span>;
}

Generating Localized URLs

import { getLocalePath } from "#src/i18n/get-locale-path.ts";

getLocalePath("/design-system", locale); // → "/design-system" (en) or "/zh/design-system" (zh)

Build Pipeline

Codegen (pnpm --filter web codegen:i18n)

The codegen script in packages/i18n-codegen/ does:

1. Extracts all t() calls from source files via AST parsing
2. Generates global JSON bundles: apps/web/src/_generated/i18n/translations.{en,zh}.json
3. Traces client component imports from each page/layout entry point
4. Generates per-page client bundles: apps/web/src/_generated/i18n/client/{name}.{en,zh}.json
5. Generates loader modules: apps/web/src/_generated/i18n/client-loaders/{name}.ts
6. Generates manifest: apps/web/src/_generated/i18n/manifest.json

pnpm dev in apps/web watches and regenerates, and build and test run it first. Outside those, run codegen after adding/changing any t() call, or the Babel plugin won't find the translation key at runtime.

Babel Plugin (packages/babel-plugins/src/i18n/)

Runs at compile time (both dev and build). Transforms:

• t({en, zh}) → __i18n_lookup(key) (server) or i18nLookup(_translations, key) (client)
• t({en, zh}, { parse: true }) → __i18n_lookupParse(key) or i18nLookupParse(_translations, key)
• Client: declares const _translations = useI18nTranslations() at the top of each component or hook that calls t(). A local helper that calls t() gets the translations as a new first parameter, which each caller passes. The rewrite runs in the plugin's pre(), before React Compiler, so the compiler caches each lookup by the translations.
• Auto-injects setLocale for page files with t() calls
• Auto-wraps returns with <ClientTranslationsProvider> for manifest entries

Common Patterns

Adding Translations to a New Page

// apps/web/src/app/[locale]/my-page/page.tsx
import { t } from "#src/i18n.ts";

export default function Page() {
  return (
    <div>
      <h1>{t({ en: "My Page", zh: "我的页面" })}</h1>
      <p>{t({ en: "Some content", zh: "一些内容" })}</p>
    </div>
  );
}

Then run pnpm --filter web codegen:i18n to regenerate bundles.

Adding Translations to a Client Component

// apps/web/src/<area>/my-component.tsx
"use client";

import { t } from "#src/i18n.ts";

export function MyComponent() {
  return <span>{t({ en: "Click me", zh: "点击我" })}</span>;
}

The parent page/layout must be in the manifest for client translations to work. Run pnpm --filter web codegen:i18n — the codegen traces imports and auto-generates the client bundle.

Rich Text with Markup

{
  t(
    {
      en: "Read our <strong>terms of service</strong>",
      zh: "阅读我们的<strong>服务条款</strong>",
    },
    { parse: true },
  );
}

Common Mistakes

• Using variables or template literals in t() — values must be string literals
• Forgetting to run pnpm --filter web codegen:i18n after adding new t() calls outside pnpm dev
• Manually adding setLocale to page files — the Babel plugin does this automatically
• Creating separate translations.json files — translations live inline in the component
• Calling t() outside render scope — t() must be called directly in a React component body, custom hook, or generateMetadata(). It cannot be used in useEffect, event handlers, callbacks (.map(), .then()), setTimeout, module scope, or exported non-component functions. The ESLint rule @tuja/no-t-outside-render enforces this. Non-exported helper functions are allowed only if every call site is in render scope.