Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

9.1 KB
Raw Blame

Web UI internationalisation

The dashboard speaks English and Simplified Chinese (zh-CN). English is the default: a request without a locale cookie renders English. Nothing about the URL changes — there is no /{locale}/... prefix — so every existing link, bookmark and uptime probe keeps resolving to the same page.

How the locale is chosen

  1. Cookie NEXT_LOCALE — read server-side on every request by src/i18n/request.ts, which returns the messages for that locale. This is what makes curl -H 'Cookie: NEXT_LOCALE=zh-CN' / render Chinese.
  2. localStorage key repowise:locale — a client-side mirror the switcher writes next to the cookie, restored on load when the cookie is missing (cleared cookies, a different browser profile).
  3. Fallback — anything unknown or absent resolves to en (resolveLocale in src/i18n/config.ts never throws).

English is the source of truth

messages/en.json carries every key. A locale catalog may lag behind it: when a key is missing, src/i18n/request.ts layers the catalog on top of the English one (withFallback in src/i18n/fallback.ts), so the English string renders at runtime instead of the raw key or a MISSING_MESSAGE throw. UI copy can therefore change without every locale being updated in the same commit, and npm run i18n:check reports the gaps as warnings (exit 0).

Files

Path Role
src/i18n/config.ts Locale registry (LOCALES, DEFAULT_LOCALE), the cookie name, the storage key, resolver helpers, endonym labels
src/i18n/fallback.ts withFallback — layers a catalog over en.json so missing keys render English
src/i18n/request.ts next-intl request config: cookie → locale → messages; sets the fixed UTC time zone
src/app/layout.tsx getLocale() drives <html lang>; NextIntlClientProvider hands messages to client components
src/components/layout/language-switcher.tsx The 中 / EN control (sidebar footer and mobile nav)
messages/en.json Source of truth for the key set
messages/zh-CN.json Chinese catalog — keys it has not reached yet render English
scripts/check-i18n-keys.mjs Catalog freshness report (npm run i18n:check) — warnings, exit 0
scripts/check-i18n-usage.mjs Resolves every t("…") call against en.json (npm run i18n:usage) — hard failure
scripts/find-untranslated.mjs Untranslated-copy detector (npm run i18n:todo)
scripts/check-i18n-icu.mjs ICU compile check for every message (npm run i18n:icu)
i18n-untranslated-allowlist.json Strings that must stay English everywhere, each with an audit note

Messages are imported statically in request.ts rather than read from disk at runtime: the build is output: "standalone", and a fs.readFile on a computed path is not traced into the bundle, so the catalogs would be missing in a production container.

Switching language

LanguageSwitcher writes the cookie, mirrors it to localStorage, sets document.documentElement.lang and calls router.refresh(). The refresh re-renders the server tree in the new language without a full page load, so scroll position and route state survive. No reload is required.

Using a string in a component

Server components (async) use getTranslations:

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

export default async function Page() {
  const t = await getTranslations("views.files");
  return <PageShell title={t("title")} description={t("description")} />;
}

Client components ("use client") use useTranslations:

"use client";
import { useTranslations } from "next-intl";

export function Panel() {
  const t = useTranslations("views.costs");
  return <span>{t("spendTitle")}</span>;
}

Placeholders are ICU: t("description", { repo: repo.name }) against "description": "… for {repo}. …".

Adding a string

  1. Add the key to the right namespace in messages/en.json. English is the source of truth, and for an English-only change this is the only catalog you have to touch.
  2. Reference it with t("key") in the component.
  3. Optional, and it can come later: add the same key to messages/zh-CN.json, translated rather than copied from the English. Nothing breaks while it is missing — withFallback renders the English string, and npm run i18n:check reports the gap as a warning (exit 0) — so a translation can land in a follow-up commit, or from a translator who never opens a .tsx.
  4. Run npm run i18n:usage (the key resolves), npm run i18n:icu (the message compiles) and npm run i18n:check (it prints any catalog missing the key as a warning — the string renders English until a translator adds it — and any orphaned key that never renders).

Namespace layout: common.* (buttons), shell.* (app frame, nav chrome, command palette), nav.* and breadcrumb.* (navigation labels), errors.* (error/404 surfaces), dashboard.* (the repositories dashboard), attention.* (dashboard attention sentences), views.<view>.* (per-view titles, descriptions, section headers).

Finding untranslated copy

npm run i18n:todo walks every .tsx under src/ and prints the user-visible strings that are still hard-coded, so "the UI is still English somewhere" is a command rather than an opinion:

npm run i18n:todo                      # whole of src/, grouped by file
npm run i18n:todo -- src/components    # one subtree
npm run i18n:todo -- --json            # machine-readable, for follow-up work
npm run i18n:todo -- --strict          # exit 1 while anything is untranslated

It reports three kinds of copy:

Kind Example
jsx-text <span>Save changes</span>
jsx-attribute placeholder="Search", aria-label="Close", title=, alt=, label=, hint=, description=
string-exit toast.error("Saved"), confirm("Delete this repo?"), alert(…), window.prompt(…), new Error(…)

What it ignores is not copy: className, data-*, key, id, imports and types, comments, test files, the contents of <code>, <pre>, <kbd> and <samp>, URLs, paths, file names, versions, ENV_VAR=value snippets and bare identifiers. --min-length=<n> raises the floor for very short strings, --group-depth=<n> changes how the summary buckets directories. --json prints the whole result (scannedFiles, hitFiles, totalHits, allowlistedHits, byDirectory, hits, allowlisted) with no timestamp, so two runs are diffable.

The report only counts strings the allowlist does not cover. --show-allowed adds the allowlisted ones back, with the reason that excused them.

What belongs in the allowlist

i18n-untranslated-allowlist.json holds the strings that must stay English in every locale. An entry is { "value": "GitHub", "reason": "…" }, or a { "value": "^…$", "match": "regex", "reason": "…" } rule. The scanner exits 2 on an entry without a real reason, because the allowlist is meant to be auditable rather than a place to park work, and it warns about entries that matched nothing so the list cannot rot silently.

The bar is "translating this would be wrong", not "translating this is work":

  • brand and product names — repowise, GitHub, GitLab, MCP, PageRank;
  • identifiers, paths, file names, versions, units, code snippets shown verbatim;
  • developer-only strings that never reach a user, e.g. React context guards.

Everything else — sentences, labels, hints, tooltips, error copy, empty states — is work, and work is exactly what this list exists to expose.

In CI, or at the end of a sweep

src/ is at zero, so the gate is the whole tree:

npm run i18n:todo -- --strict

That exits 1 while any string in src/ is still hard-coded, which turns "someone forgot a t()" into a failing check instead of a review comment. Keep the other two beside it: npm run i18n:check prints keys a catalog is missing (a warning — they render English), and npm run i18n:icu compiles every message with ICU, so a malformed plural fails here instead of throwing on the page that renders it.

Adding a second language

  1. src/i18n/config.ts: append the tag to LOCALES and add its endonym to LOCALE_LABELS. Leave DEFAULT_LOCALE alone unless the new language should become the fallback.
  2. Create messages/<tag>.json carrying the keys you have translated — you do not have to cover en.json in one go; anything missing renders English.
  3. src/i18n/request.ts: import the catalog and add it to the MESSAGES map. The fallback layering is already wired.
  4. npm run i18n:check — it lists any key the new catalog has not reached yet.
  5. The language switcher maps over LOCALES, so the new language appears in the control on its own.

What is deliberately not translated

Code (file contents, symbol names, diffs), AI-generated wiki prose, repository and branch names, and API-returned text. The UI chrome around them is translated; the payload is shown as written.

packages/ui stays language-agnostic: it is a shared package, so it receives its copy through props/children and the packages/web side supplies the translated strings.