Every spec checked against the code rather than against itself, in four passes that each read the branch's commits and then the source: - CLI-SPEC/CLI-GUIDE: one JSON document per command (with the per-command table and the paths that print nothing), environment selection, logging, Ctrl-C and exit 130, the prompts as they are rather than the [A]bort and countdown that never existed, `.heldBack`, a `pipdock audit` section, and the rules every mutating command now follows. - ARCHITECTURE/DATA-FLOW/ERROR-CATALOG: the Engine trait's real signatures, Requires-Python's three checkpoints, store v4 and the log folder, §7's return types and events, the state machine with re-probing and Force latest, where each §9 invariant is enforced, and 35 codes in 32 rows. - SECURITY/TESTING/RELEASE-CI/CODE-HEALTH-SPEC: the PEP 668 override as built, four browser hosts and the exact capability set, attested releases, the new CI, the tools constraints, and test tiers that describe what runs rather than what was planned. - UI-SPEC/PRD/README/I18N: the screens as they render, the keyboard, tokens and their contrast sweep, the feature matrix's status, attestation instructions, and I18N's one stated exception. ROADMAP gets the 1.4.0 record — what was wrong, what running found that reading did not, what was deliberately not done — and the **Audit backlog**: every finding not fixed, with where it is and why it waited. CLAUDE.md's counts and contradictions are corrected, with the rules this release left behind. changelog/1.x.md has the 1.4.0 entry, including "Changed for scripts" and "You will see this once". AI-DISCLOSURE, README and About say which model and who released what. The legal documents' effective date moves to the release date. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
48 lines
6.0 KiB
Markdown
48 lines
6.0 KiB
Markdown
# 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, never raw key names in the UI. **The fallback is silent**, whatever `i18n.ts`'s comment says: i18next calls `missingKeyHandler` only under `saveMissing: true`, which is off, and a key `vi` lacks but `en` has is not missing to i18next at all — so the build-time test is the only thing that notices (audit backlog U59).
|
|
|
|
**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 35 of them (PD-ENG-004 made the thirty-fifth in 1.4.0), 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.
|
|
|
|
**One stated exception, since 1.4.0: the startup-failure dialog.** When the data folder cannot be opened, the GUI says so before Tauri starts — so before any webview exists to load a catalog. `startup_failed` in `src-tauri/src/lib.rs` is therefore the one place GUI copy is written in Rust, and it is written in **both languages at once**, an English sentence and then a Vietnamese one (the stored language choice is in the folder that could not be opened), followed, untranslated, by the catalog code, the error's own message and the log's path. Before 1.4.0 the same failure was a panic inside Tauri's setup hook, and a release build has no console: the user double-clicked and nothing happened. Anything added to that dialog is added in both languages there, because no catalog can reach it.
|
|
- **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, and **stored** (since 1.4.0). `settings.locale` holds the user's explicit choice and `null` means "follow the OS"; the two are kept apart so that saving any other setting cannot pin the language the OS happened to resolve to. Until 1.4.0 every save sent `null`, so a choice lasted until the window closed. Settings load at start, before the legal gate, so the gate is shown in the chosen language too. **`<html lang>` follows the UI language**: `index.html` ships `lang="en"` and nothing changed it, so a screen reader read Vietnamese copy as English. Dates via `Intl.DateTimeFormat` with the active locale; file sizes binary (MiB) with locale decimal separators. Not yet everywhere for dates: the snapshot timeline formats its own, but Code Health's and the Security tab's "Checked …" lines print the report's raw timestamp (audit backlog U50). Package names, versions, engine output, error codes, **email addresses, URLs and SPDX identifiers** are **never** translated or reshaped.
|
|
|
|
The last three live as TypeScript constants beside the component that renders them, not in the catalogs — a catalog entry is a thing a translator is invited to change, and an address they changed would route mail nowhere. They reach JSX as *expressions*, which is also what keeps the `pipdock/no-jsx-literals` rule (§1) correct about them: it examines JSX text and string literals inside expression containers, never an identifier. `PdAbout`'s `CONTACT`, `PdSettings`'s engine ids and `PdEmptyState`'s glyph are the same escape hatch used for the same reason.
|
|
|
|
## 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 (`en-XA`-style bracketed expansion) to catch clipping — development only, toggled with `Ctrl+Alt+P` under `npm run dev`, never offered in Settings and never in a release bundle; 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.
|