Files
pipdock/docs/I18N.md
T
poli0981andClaude Opus 5 5e8d78bb27 docs: add design documentation baseline
Commits the full v0.1 design suite written during the design phase:
PRD, architecture, data flow, UI/CLI specs, code-health spec, error
catalog, security, testing, release/CI and i18n docs, plus the roadmap.

The legal documents (EULA, disclaimer, privacy policy, third-party
notices) must be committed publicly because the in-app legal gate links
to their GitHub URLs at first run.

Also adds .gitignore, which the repo was missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 17:08:14 +07:00

2.8 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,envs,packages,plan,health,legal,errors}.json. en is the source of truth; a CI script fails the build if vi is missing keys (untranslated keys fall back to EN at runtime with a console warning, never raw key names in the UI).
  • 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).

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.