Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
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
- Cookie
NEXT_LOCALE— read server-side on every request bysrc/i18n/request.ts, which returns the messages for that locale. This is what makescurl -H 'Cookie: NEXT_LOCALE=zh-CN' /render Chinese. localStoragekeyrepowise: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).- Fallback — anything unknown or absent resolves to
en(resolveLocaleinsrc/i18n/config.tsnever 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
- 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. - Reference it with
t("key")in the component. - 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 —withFallbackrenders the English string, andnpm run i18n:checkreports 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. - Run
npm run i18n:usage(the key resolves),npm run i18n:icu(the message compiles) andnpm 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
src/i18n/config.ts: append the tag toLOCALESand add its endonym toLOCALE_LABELS. LeaveDEFAULT_LOCALEalone unless the new language should become the fallback.- Create
messages/<tag>.jsoncarrying the keys you have translated — you do not have to coveren.jsonin one go; anything missing renders English. src/i18n/request.ts: import the catalog and add it to theMESSAGESmap. The fallback layering is already wired.npm run i18n:check— it lists any key the new catalog has not reached yet.- 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.