**26 of the 32 codes had no copy at all.** A PEP 668 refusal, an MSVC-missing
build failure and a full disk all rendered as "An unexpected error occurred."
with a code beside them — and silently, because `PdErrorRow` falls back
deliberately rather than leaking `PdError.message`, which is English developer
text. Nothing failed; the app simply had nothing to say about five sixths of what
can go wrong.
The codes move to `locales/{en,vi}/errors.json`, merged into the single `common`
namespace at init. I18N §1 named seven namespaces; the app ships one, because a
real second namespace means `t('errors:PD-NET-001')` at every call site —
i18next's `nsSeparator` is `:` — bought with lazy loading a desktop app that
bundles both catalogs cannot use. The error codes still earn their own *file*:
there are 32, they are the only keys whose names are a contract with Rust rather
than with a screen, and keeping them reviewable is worth one import. §1 is
amended to say so rather than left describing something that was never built.
`i18n.test.ts` now checks them against `codes.json`, generated from `Code::ALL`.
A hand-written list in TypeScript would drift the moment a code was added and go
on passing over an incomplete catalog. It asserts both directions — no code
without copy, no copy without a code — and the ≤ 90-char cap I18N §4 states,
which was aspiration until now. Verified by breaking the catalog deliberately:
both directions fail, then pass again once restored.
Adding a code is now an eight-place change, and CLAUDE.md says which eight.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.5 KiB
PipDock — Internationalization (EN + VI)
Version 0.1 · 2026-07-17 · Scope decision: EN + VI in v1; JP is P2-6.
1. Mechanics
-
GUI: i18next + react-i18next; catalogs at
ui/src/locales/{en,vi}/{common,errors}.json.enis the source of truth;ui/src/i18n.test.tsfails the build ifviis missing keys, and untranslated keys fall back to EN at runtime with a console warning, never raw key names in the UI.Two files, one namespace — amended in S7. This section originally named seven namespaces. The app merges its catalogs into a single
commonat init, because a real second namespace meanst('errors:PD-NET-001')at every call site (i18next'snsSeparatoris:) — churn across every screen, bought with lazy loading a desktop app that bundles both catalogs cannot use. The error codes still get their own file, and that part earns itself: there are 32 of them, they are the only keys whose names are a contract with Rust rather than with a screen, and the test checks them against a generated copy ofCode::ALLrather than against a list someone maintains by hand. -
Core: Rust emits codes and structured data only (catalog codes, counts, package names); all human phrasing happens in the frontend catalogs. This keeps CLI (English-only v1) and GUI consistent without duplicating strings in Rust.
-
No hardcoded strings rule: enforced by an eslint rule on JSX literals (allowlist:
PipDock, package names, versions, codes). -
Interpolation via ICU-style placeholders:
"updateSummary": "{{ok}} successful, {{failed}} failed"/"{{ok}} thành công, {{failed}} thất bại". Plurals: use i18next plural forms; note Vietnamese has a single plural form — never build strings by concatenatings.
2. Locale behavior
Default locale = OS UI language if vi, else en; switchable in Settings, applied live. Dates via Intl.DateTimeFormat with the active locale; file sizes binary (MiB) with locale decimal separators. Package names, versions, engine output, and error codes are never translated or reshaped.
3. Glossary (consistency contract)
| EN | VI | Note |
|---|---|---|
| environment | môi trường | |
| package | gói | not "thư viện" in UI copy (broader than libraries) |
| update / upgrade | cập nhật | one term for both in UI |
| held back | bị giữ lại | conflict preview |
| pin / pinned | ghim / đã ghim | |
| snapshot / rollback | ảnh chụp / khôi phục | "khôi phục" for the action |
| uninstall | gỡ cài đặt | |
| dependency | phụ thuộc | |
| force latest | ép bản mới nhất | keep the "ép" bluntness — it should sound risky |
| dry run / preview | xem trước | user-facing term is always "xem trước" |
| queue ("dock bay") | hàng chờ | dock-bay flavor stays EN-only in code names |
4. Copy rules
- Vietnamese copy uses "bạn", concise and direct; avoid literal translations of English idioms.
- Warning copy must not soften risk in translation — "this will break X" ⇒ "thao tác này sẽ làm hỏng X".
- Legal gate summaries are localized, but the linked legal documents themselves are EN (governing) with a VI courtesy note at top of each (see legal/ files).
- Error one-liners ≤ 90 chars in both languages (fit the inline row) — asserted, not aspired to, over every
Code::ALLvariant in both locales.
5. QA
Pseudo-locale build target (en-XA-style bracketed expansion) to catch clipping; VI sweep of all mutation dialogs is part of the manual release charter (TESTING §4); screenshots in both locales attached to release PRs for the three core screens.