Internationalization (i18n)

User-facing strings live in @bondery/translations. Each app calls generated namespace hooks — not generic t(key, { ns }) — so TypeScript can autocomplete keys and prefixes.

Locales

Source of truth: packages/schemas/locale/supported-locales.json. Exported as SUPPORTED_LOCALES from @bondery/schemas/locale.

To add a language, follow Add a new language.

Layout

packages/translations/
  manifest.json          # namespaces + preload groups
  src/locales/{locale}/  # one JSON file per namespace

A namespace is the filename without .json (folders are organizational only). Examples: common, GroupsPage, MobileSettings.

Architecture decision: typed namespace hooks (not selectors)

Phase 0 spike (2026): We evaluated i18next enableSelector: true and selector syntax (t($ => $.AddGroupModal.Title)).

Runtime behavior is unchanged (same JSON, preload groups, resourceLoader). Only the hook surface and generated types are stricter.

Type system (Phase 2)

Types are generated from manifest.json + English locale JSON:

Codegen order (pnpm run build -w @bondery/translations):

1. i18next-cli types — lint/status tooling types (path-based resources.d.ts, kept for CLI only)
2. generate-i18n-catalog.mjs — Catalog, prefix unions, patches i18next.d.ts
3. generate-client-i18n-hooks.mjs — per-app hooks with prefix overloads

Hooks (use these in app code)

Webapp

import { useGroupsPageTranslations, useCommonTranslations } from "@/lib/i18n/generated/hooks";

// With keyPrefix — keys are relative to the branch; prefix is type-checked
const t = useGroupsPageTranslations("AddGroupModal");
t("Title"); // → GroupsPage.AddGroupModal.Title

// Without keyPrefix — use full dotted paths within the namespace
const tPage = useGroupsPageTranslations();
tPage("AddGroupModal.Title");

const tCommon = useCommonTranslations();
tCommon("actions.cancel");

Prefix typo → compile error:

useSettingsPageTranslations("DataManagement.VCardImportt"); // not in SettingsPagePrefix

Server metadata:

import { getPeoplePageTranslations } from "@/lib/i18n/generated/hooks.server";

const t = await getPeoplePageTranslations();

Do not use: useWebTranslations("…"), getWebTranslations("…"), or t(key, { ns: "…" }).

Mobile

import { useMobileSettingsTranslations } from "@/lib/i18n/generated/hooks";

const t = useMobileSettingsTranslations();
t("Title");

Do not use: useMobileTranslations() with per-call { ns: "…" }.

Chrome extension

import { useExtensionPopupTranslations } from "@/lib/i18n/generated/hooks";

const t = useExtensionPopupTranslations("LoggedOut");
t("Title");

Hooks are regenerated from manifest.json when you run pnpm run build -w @bondery/translations. Each hook hardcodes its namespace and type-checks keyPrefix branches.

Escape hatches (dynamic keys)

Most call sites should use generated hooks and literal keys. Use these only when keys are computed at runtime.

LooseTranslateFn

For utilities that map runtime values to keys (interaction types, slash commands, social tooltips):

import type { LooseTranslateFn } from "@bondery/translations";
import { useInteractionTypesTranslations } from "@/lib/i18n/generated/hooks";

const t = useInteractionTypesTranslations() as LooseTranslateFn;
t(dynamicKey);

transT — <Trans> component

next-i18next / react-i18next <Trans> expects a plain TFunction. Cast namespace-scoped t:

import { transT } from "@/lib/i18n/transT";
import { useSettingsPageTranslations } from "@/lib/i18n/generated/hooks";

const t = useSettingsPageTranslations("DataManagement.DeleteAccount");
<Trans t={transT(t)} i18nKey="ConfirmLabel" />

optionalPluralFragment

Plural fragments used as interpolation values inside a parent sentence:

import { optionalPluralFragment } from "@/lib/i18n/optionalPluralFragment";

t("Summary", {
  skippedDetails: optionalPluralFragment(t, "Skipped_one", skippedCount, { count: skippedCount }),
});

Namespaces (i18next best practices)

Follow i18next namespaces:

• Semantic splits: common, validation, glossary
• Per feature/page: GroupsPage, MobileSettings, …
• Preload groups in manifest.json — load only what a route/screen needs

Follow interpolation best practices:

• Prefer separate keys when grammar varies by interpolated value (e.g. payment type, gender)
• Use context / plurals / formatting for locale-specific rules
• Reserve interpolation for runtime-only values (user input, timestamps)

Regenerate types and hooks

After editing locale JSON or manifest.json:

pnpm run build -w @bondery/translations

This rebuilds Catalog types, prefix unions, i18next augmentations, and per-app generated/hooks*.ts.

CI checks

API error code translations use pnpm run check:api-errors:translations (part of check:api-errors), not check:i18n.

For rich text with embedded links or markup, prefer TypedTrans (webapp) with a single translation key and component placeholders — see apps/webapp/src/lib/i18n/TypedTrans.tsx.

Run these before opening a PR that touches copy.

Related

• Add a new language
• packages/translations/README.md — manifest layout and mirror tooling