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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user