Files
pipdock/docs/I18N.md
T
poli0981andClaude Opus 5.5 7124227262 docs: the specs say what the code does; 1.4.0 recorded, with its audit backlog
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>
2026-10-17 00:55:27 +07:00

6.0 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, 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.