Internationalization

@repo/i18n is the single message store; the Next.js app consumes it through next-intl. Strings live in packages/i18n/translations/{locale}/{scope}.json and the locale registry is the i18nConfig export from @repo/config. i18n is always on - you tune it by editing locales and JSON, never a feature flag.

Where translations live

Two files load per locale: the active scope plus shared.json layered beneath it. You write en only; the translation pipeline generates the rest.

packages/i18n/translations/
  en/
    web.json      # frontend-facing copy (default locale - edit this)
    shared.json   # keys reused across surfaces
  ro/
    web.json      # auto-generated from en/web.json
    shared.json   # auto-generated

How messages load

Messages resolve server-side per request in apps/web/i18n/request.ts.

Routing (apps/web/i18n/routing.ts) uses localePrefix: "as-needed" - default en is un-prefixed, ro lives under /ro/.... With localeDetection: false the URL prefix is the sole source of truth on first visit; the <SuggestLocale> card offers a switch to the visitor's detected locale instead of auto-redirecting, and updateLocale persists the choice to the cookie.

Using translations

Namespace by key prefix, then call t:

import { useTranslations } from "next-intl";

export function Welcome() {
  const t = useTranslations("dashboard");
  return <h1>{t("welcome_message")}</h1>; // dashboard.welcome_message
}

Async server components read messages without a hook via next-intl/server:

import { getTranslations } from "next-intl/server";

export default async function Page() {
  const t = await getTranslations("dashboard");
  return <h1>{t("welcome_message")}</h1>;
}

For links and redirects use the locale-aware Link, redirect, and useRouter from apps/web/lib/navigation.ts (not next/link / next/navigation) - they auto-apply the locale prefix.

Translation pipeline

@repo/translate turns your en source into every other locale. A pre-commit hook runs it automatically; you can also run it by hand.

Incremental by hash. packages/translate/.meta/*.json stores a content hash per source key and document for each locale, so each run only (re)translates added or changed en text and prunes what you removed.

Translating with your coding agent

No OpenRouter key, or rather use your own model? The bundled translate skill runs the same pipeline with your AI agent as the translator: type /translate (add anything you like - one locale, a glossary, which model its subagents use) or ask it to translate the project.

Both paths share the ledger, so a translation the agent applied is never redone by the hook or by pnpm translate until its source changes.

Adding or removing a language

Each flag is derived from the entry's iso region subtag (de-DE resolves to the German flag). For a script-based tag with no region, add an explicit flag country code: { name: "中文", iso: "zh-Hans", flag: "CN" }.

Frequently asked questions

Which files do I edit? Only packages/i18n/translations/en/*.json. The ro files (and any future locale) are generated from en, so hand edits there are overwritten.

Why is my new key showing in English in another locale? That is the fallback working. Translated copy lands once translation runs - on commit via the hook or pnpm translate by hand (both need OPENROUTER_API_KEY), or through your agent with the translate skill.

Can I use plurals like "1 item / 2 items"? Yes - write an ICU plural, {count, plural, one {# item} other {# items}}, and pass count. Every branch carries the whole phrase and other is required; translation adds the forms each language needs (Romanian's few, for example).