diff --git a/docs/i18n.md b/docs/i18n.md index 1af0024421..e98936fad5 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -594,6 +594,60 @@ file to `i18nGuardFiles`, because allowlisting it claims a completeness nobody has. The last area to migrate adds it. Say so in your guard comment, naming which entries are still English and who owns them. +### An existing key is not automatically the right key + +When the same copy is rendered from two places and one of them is already +migrated, reaching for the key that already exists looks like the careful move. +It is the one shape in this guide that can **silently rewrite user-visible +English**, and every gate passes while it does. + +Two surfaces rendering "the same" sentence have usually **drifted**. Settings → +System had an unreferenced `app/settings/system//page.tsx` twin for every +route, and the twins were migrated at a different time by a different PR: + +| surface | copy | +|---|---| +| `SETTINGS_ROUTES` — live, what users see | `Create a diagnostic ZIP with frontend and backend logs.` | +| `app/settings/system/logs/page.tsx` — dead → `settings:logsPageDescription` | `Download a bounded diagnostic ZIP containing frontend and backend logs.` | + +Pointing the live route at the existing key changed the sentence on a shipping +page. `pnpm lint`, `pnpm run i18n:check`, the ratchet and 8,000+ unit tests were +all green — the key resolved, the catalogs matched, nothing was hardcoded. The +copy was simply *different*. `feature-toggles` had drifted the same way in the +same directory. + +Nothing in the toolchain can catch this, because every check verifies that a key +resolves, not that it resolves to the string the route used to render. The only +thing that caught it was a single Playwright assertion: + +``` +e2e/tests/system/logs-page.spec.ts:16 + getByText('Create a diagnostic ZIP with frontend and backend logs.') +``` + +One of nine routes happened to pin its description. The other eight could have +drifted with nothing failing. + +**Diff the two surfaces before reusing a key**, and when a route group's headers +are duplicated anywhere, pin them: + +```bash +# What does the live surface actually render today? +git show origin/main:apps/web/src/settings-routes.tsx | grep -A6 '"/settings//"' +# What does the existing key say? +node -e 'console.log(require("./apps/web/src/locales/en/.json").)' +``` + +`apps/web/components/settings/system/system-route-copy.test.ts` is the shape of +the guard: a table of every route's title and description as English, asserted +byte-for-byte. It converts "I diffed them carefully" into something that stays +true after you leave. + +The underlying defect is the duplication itself. Unreferenced pages that +re-render live copy will drift again, and the next migration inherits the same +trap — which is why deleting a dead twin is a correctness change, not tidiness. +Do it in its own PR, not inside a copy-only migration. + ## Adding a real language 1. Add the locale to `SUPPORTED_LOCALES` + `LOCALE_LABELS` in