Files
pipdock/docs/I18N.md
T
poli0981andClaude Opus 5 46c1936650 feat(i18n): a one-liner for every catalog code, in both locales
**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>
2026-08-09 21:46:25 +07:00

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. en is the source of truth; ui/src/i18n.test.ts fails the build if vi is 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 common at init, because a real second namespace means t('errors:PD-NET-001') at every call site (i18next's nsSeparator is :) — 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 of Code::ALL rather 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 concatenating s.

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::ALL variant 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.