docs(i18n): an existing key is not automatically the right key (#2217)

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
João Salavisa
2026-08-03 17:29:48 +02:00
committed by GitHub
parent 25564efeb8
commit 13b9f4e43f
+54
View File
@@ -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/<route>/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/<area>/<route>"'
# What does the existing key say?
node -e 'console.log(require("./apps/web/src/locales/en/<ns>.json").<key>)'
```
`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