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>
2.8 KiB
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.enis the source of truth; a CI script fails the build ifviis 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 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).
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.