From 46c1936650a099b59c7dde49a6fecf9c5a3ad518 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Sun, 9 Aug 2026 21:22:32 +0700 Subject: [PATCH] feat(i18n): a one-liner for every catalog code, in both locales MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **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 --- CLAUDE.md | 8 ++++--- crates/pipdock-core/src/fixtures.rs | 12 ++++++++++ docs/I18N.md | 6 +++-- ui/src/i18n.test.ts | 37 +++++++++++++++++++++++++++++ ui/src/i18n.ts | 20 ++++++++++++++-- ui/src/locales/en/common.json | 7 ------ ui/src/locales/en/errors.json | 36 ++++++++++++++++++++++++++++ ui/src/locales/vi/common.json | 7 ------ ui/src/locales/vi/errors.json | 36 ++++++++++++++++++++++++++++ ui/src/test/fixtures/codes.json | 34 ++++++++++++++++++++++++++ 10 files changed, 182 insertions(+), 21 deletions(-) create mode 100644 ui/src/locales/en/errors.json create mode 100644 ui/src/locales/vi/errors.json create mode 100644 ui/src/test/fixtures/codes.json diff --git a/CLAUDE.md b/CLAUDE.md index 3e3cf3b..1b53ad8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,9 +15,11 @@ The design is fully specified. Read in this order; do not invent behaviour that 6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **32 in Rust** (`Code::ALL`, pinned by two tests); the doc tabulates 30 because it folds `PD-HLT-001..003` into one row. Adding a code means the catalog, `Code::ALL`, both counts, the - "no code without a fixture" gate in `classifier_corpus.rs`, both locale catalogs, and - re-blessed goldens — `golden__schema-Code.snap` **and every schema that embeds it** - (`StepResult`, `ExecutionSummary`) — the gate will tell you which you forgot + "no code without a fixture" gate in `classifier_corpus.rs`, **both `locales/*/errors.json`**, + a regenerated `codes.json` (`cargo run -p xtask -- ipc-fixtures`), and re-blessed goldens — + `golden__schema-Code.snap` **and every schema that embeds it** (`StepResult`, + `ExecutionSummary`). Eight places; the gates will tell you which you forgot, including + `i18n.test.ts`, which now fails on a code with no copy in either language 7. `docs/CODE-HEALTH-SPEC.md`, `docs/SECURITY.md`, `docs/TESTING.md`, `docs/RELEASE-CI.md`, `docs/I18N.md`, `docs/ROADMAP.md` 8. `legal/` — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs) diff --git a/crates/pipdock-core/src/fixtures.rs b/crates/pipdock-core/src/fixtures.rs index 188bddb..c57a47e 100644 --- a/crates/pipdock-core/src/fixtures.rs +++ b/crates/pipdock-core/src/fixtures.rs @@ -287,6 +287,17 @@ fn rollback_preview() -> crate::flow::RollbackPreview { } } +/// Every catalog code, in `Code::ALL` order. +/// +/// Not a payload any command returns — a *contract*. `i18n.test.ts` asserts that every code has a +/// one-liner in both locales, and it has to read the list from somewhere: a hand-written array in +/// TypeScript would drift the moment a code is added, and the test would go on passing over a +/// catalog that is no longer complete. Generated here, so `cargo run -p xtask -- ipc-fixtures` +/// and its staleness test carry it the same way they carry everything else. +fn codes() -> Vec { + crate::errors::Code::ALL.to_vec() +} + /// Every fixture, as `(file name, contents)`. /// /// # Errors @@ -302,6 +313,7 @@ pub fn ipc_fixtures() -> serde_json::Result> { ("guard_report.json", render(&guard_report())?), ("snapshot_list.json", render(&snapshot_list())?), ("rollback_preview.json", render(&rollback_preview())?), + ("codes.json", render(&codes())?), ]) } diff --git a/docs/I18N.md b/docs/I18N.md index 9b3711a..b4ae7ec 100644 --- a/docs/I18N.md +++ b/docs/I18N.md @@ -4,7 +4,9 @@ ## 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). +- **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`. @@ -34,7 +36,7 @@ Default locale = OS UI language if `vi`, else `en`; switchable in Settings, appl - 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). +- 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 diff --git a/ui/src/i18n.test.ts b/ui/src/i18n.test.ts index 7d478f4..6a0e233 100644 --- a/ui/src/i18n.test.ts +++ b/ui/src/i18n.test.ts @@ -1,5 +1,12 @@ import { describe, expect, it } from 'vitest' import { FALLBACK_LOCALE, resolveLocale, resources, SUPPORTED_LOCALES } from './i18n' +import codes from './test/fixtures/codes.json' + +/** `Code::ALL`, generated from the Rust enum — see `crates/pipdock-core/src/fixtures.rs`. */ +const CODES: readonly string[] = codes + +/** docs/I18N.md §4: an error one-liner has to fit the inline row. */ +const MAX_ONE_LINER = 90 /** Collect every leaf key path in a nested catalog, e.g. `nav.updates`. */ function keyPaths(obj: unknown, prefix = ''): string[] { @@ -19,6 +26,36 @@ function pluralBase(key: string): string { return key.replace(/_(zero|one|two|few|many|other)$/, '') } +describe('the error catalog', () => { + // The gap S7 exists to close: 26 of the 32 codes had no copy at all, so a PEP 668 refusal, an + // MSVC-missing build and a disk-full all rendered as "An unexpected error occurred." with a code + // beside them. `PdErrorRow` falls back deliberately rather than leaking `PdError.message`, which + // is English developer text — so a missing key is silent by design, and only this catches it. + for (const locale of SUPPORTED_LOCALES) { + it(`${locale} has a one-liner for every catalog code`, () => { + const table = (resources[locale].common as { errors: Record }).errors + const missing = CODES.filter((c) => typeof table[c] !== 'string') + expect(missing, `${locale} is missing copy for: ${missing.join(', ')}`).toEqual([]) + }) + + it(`${locale} keeps every one-liner inside the row`, () => { + const table = (resources[locale].common as { errors: Record }).errors + const tooLong = CODES.filter((c) => (table[c]?.length ?? 0) > MAX_ONE_LINER).map( + (c) => `${c} (${String(table[c]?.length)})`, + ) + expect(tooLong, `over ${String(MAX_ONE_LINER)} chars: ${tooLong.join(', ')}`).toEqual([]) + }) + } + + it('has no copy for a code that no longer exists', () => { + // The other direction, and the one that rots quietly: a code removed from `Code::ALL` leaves + // copy behind that no screen can ever render. + const table = (resources.en.common as { errors: Record }).errors + const orphans = Object.keys(table).filter((k) => k.startsWith('PD-') && !CODES.includes(k)) + expect(orphans, `copy for codes that do not exist: ${orphans.join(', ')}`).toEqual([]) + }) +}) + describe('i18n catalogs', () => { it('vi has every key en has', () => { // docs/I18N.md §1: a CI script fails the build if vi is missing keys. This is that check. diff --git a/ui/src/i18n.ts b/ui/src/i18n.ts index 3b07f49..ff0c19f 100644 --- a/ui/src/i18n.ts +++ b/ui/src/i18n.ts @@ -2,7 +2,9 @@ import i18n from 'i18next' import { initReactI18next } from 'react-i18next' import enCommon from './locales/en/common.json' +import enErrors from './locales/en/errors.json' import viCommon from './locales/vi/common.json' +import viErrors from './locales/vi/errors.json' /** * i18next setup — `docs/I18N.md`. @@ -13,6 +15,18 @@ import viCommon from './locales/vi/common.json' * * §2: default locale is the OS UI language when it is Vietnamese, else English; switchable in * Settings and applied live. + * + * # One namespace, two files + * + * §1 lists seven namespaces. The app ships **one**, `common`, and merges the catalogs into it at + * init. A real second namespace would mean `t('errors:PD-NET-001')` at every call site, because + * i18next's `nsSeparator` is `:` — churn across every screen, in exchange for lazy loading that a + * desktop app with both catalogs already in the bundle cannot use. + * + * The error codes get their own *file* regardless, and that part is worth it: there are 32 of them, + * they are the only keys whose names are a contract with Rust rather than with a screen, and + * `i18n.test.ts` checks them against `Code::ALL` itself. Splitting the file keeps that reviewable + * without splitting the namespace. §1 is amended to say so. */ export const SUPPORTED_LOCALES = ['en', 'vi'] as const @@ -27,8 +41,10 @@ export function resolveLocale(languageTag: string | undefined): Locale { } export const resources = { - en: { common: enCommon }, - vi: { common: viCommon }, + // Merged, not nested: `errors.json` is `{ "errors": { … } }`, so the keys land at + // `errors.PD-XXX-NNN` exactly where `common.json` used to hold them and no call site moves. + en: { common: { ...enCommon, ...enErrors } }, + vi: { common: { ...viCommon, ...viErrors } }, } as const void i18n.use(initReactI18next).init({ diff --git a/ui/src/locales/en/common.json b/ui/src/locales/en/common.json index 12cf411..60b4188 100644 --- a/ui/src/locales/en/common.json +++ b/ui/src/locales/en/common.json @@ -268,13 +268,6 @@ "errors": { "title": "Something went wrong", "retry": "Try again", - "PD-ENV-001": "That interpreter is missing or cannot be run.", - "PD-ENV-002": "This Python is managed by the operating system.", - "PD-ENV-003": "PipDock could not read this environment.", - "PD-RES-003": "A plan is already running. Wait for it to finish, or stop it first.", - "PD-RES-004": "Other installed packages depend on these, so nothing was removed.", - "PD-SNP-001": "The snapshot could not be written, so nothing was changed.", - "PD-INT-001": "PipDock hit an internal error.", "unknown": "An unexpected error occurred." } } diff --git a/ui/src/locales/en/errors.json b/ui/src/locales/en/errors.json new file mode 100644 index 0000000..7d10a18 --- /dev/null +++ b/ui/src/locales/en/errors.json @@ -0,0 +1,36 @@ +{ + "errors": { + "PD-ENV-001": "That interpreter is missing or cannot be run.", + "PD-ENV-002": "This Python is managed by the operating system.", + "PD-ENV-003": "PipDock could not read this environment.", + "PD-ENG-001": "The selected engine is not installed or not on PATH.", + "PD-ENG-002": "This pip is too old to preview changes. Upgrade pip, then try again.", + "PD-ENG-003": "This uv is newer than PipDock understands. Switch to pip for now.", + "PD-RES-001": "These versions cannot all be satisfied at once.", + "PD-RES-002": "The environment changed since this preview. Preview it again.", + "PD-RES-003": "A plan is already running. Wait for it to finish, or stop it first.", + "PD-RES-004": "Other installed packages depend on these, so nothing was removed.", + "PD-BLD-001": "Building this package needs Microsoft C++ Build Tools.", + "PD-BLD-002": "This package's build failed while reading its own configuration.", + "PD-BLD-003": "This package had no ready-made wheel and building one failed.", + "PD-PKG-001": "This package needs a different version of Python.", + "PD-PKG-002": "No release matches that name and version.", + "PD-PKG-003": "That release was withdrawn by its author. Pick another version.", + "PD-PKG-004": "The download did not match its checksum, so it was not installed.", + "PD-NET-001": "PipDock could not reach the package index.", + "PD-NET-002": "The secure connection could not be verified.", + "PD-NET-010": "The package index could not be refreshed. The previous one still works.", + "PD-NET-011": "Code Health could not download its tools, so it stays unavailable.", + "PD-PRM-001": "PipDock is not allowed to write to this environment.", + "PD-PRM-002": "A file is in use. Close anything running from this environment.", + "PD-SNP-001": "The snapshot could not be written, so nothing was changed.", + "PD-SNP-002": "That release is no longer available, so it cannot be restored.", + "PD-SYS-001": "A path was too long for Windows. Enable long paths, or use a shorter folder.", + "PD-SYS-002": "There is not enough free disk space.", + "PD-HLT-001": "A Code Health tool is missing. Re-sync the tools environment.", + "PD-HLT-002": "A Code Health tool stopped with an error. The other results still apply.", + "PD-HLT-003": "A Code Health tool took too long and was stopped. The report is partial.", + "PD-INT-001": "PipDock hit an internal error.", + "PD-ENG-999": "The engine failed for a reason PipDock does not recognise yet." + } +} diff --git a/ui/src/locales/vi/common.json b/ui/src/locales/vi/common.json index b94575f..3ebb0b1 100644 --- a/ui/src/locales/vi/common.json +++ b/ui/src/locales/vi/common.json @@ -248,13 +248,6 @@ "errors": { "title": "Đã xảy ra lỗi", "retry": "Thử lại", - "PD-ENV-001": "Không tìm thấy hoặc không chạy được trình thông dịch đó.", - "PD-ENV-002": "Bản Python này do hệ điều hành quản lý.", - "PD-ENV-003": "PipDock không đọc được môi trường này.", - "PD-RES-003": "Đang có một kế hoạch chạy dở. Hãy đợi nó xong, hoặc dừng nó trước.", - "PD-RES-004": "Có gói khác đang phụ thuộc vào những gói này, nên chưa gỡ gì cả.", - "PD-SNP-001": "Không ghi được ảnh chụp, nên không có gì bị thay đổi.", - "PD-INT-001": "PipDock gặp lỗi nội bộ.", "unknown": "Đã xảy ra lỗi ngoài dự kiến." } } diff --git a/ui/src/locales/vi/errors.json b/ui/src/locales/vi/errors.json new file mode 100644 index 0000000..2eb2ec0 --- /dev/null +++ b/ui/src/locales/vi/errors.json @@ -0,0 +1,36 @@ +{ + "errors": { + "PD-ENV-001": "Không tìm thấy hoặc không chạy được trình thông dịch đó.", + "PD-ENV-002": "Bản Python này do hệ điều hành quản lý.", + "PD-ENV-003": "PipDock không đọc được môi trường này.", + "PD-ENG-001": "Bộ máy đã chọn chưa được cài, hoặc không có trong PATH.", + "PD-ENG-002": "Bản pip này quá cũ để xem trước thay đổi. Hãy nâng cấp pip rồi thử lại.", + "PD-ENG-003": "Bản uv này mới hơn những gì PipDock hiểu. Tạm chuyển sang pip.", + "PD-RES-001": "Không thể thỏa mãn tất cả các phiên bản này cùng lúc.", + "PD-RES-002": "Môi trường đã đổi kể từ lần xem trước này. Hãy xem trước lại.", + "PD-RES-003": "Đang có một kế hoạch chạy dở. Hãy đợi nó xong, hoặc dừng nó trước.", + "PD-RES-004": "Có gói khác đang phụ thuộc vào những gói này, nên chưa gỡ gì cả.", + "PD-BLD-001": "Biên dịch gói này cần Microsoft C++ Build Tools.", + "PD-BLD-002": "Gói này biên dịch hỏng ngay khi đọc cấu hình của chính nó.", + "PD-BLD-003": "Gói này không có bản dựng sẵn, và việc tự dựng đã thất bại.", + "PD-PKG-001": "Gói này cần một phiên bản Python khác.", + "PD-PKG-002": "Không có bản phát hành nào khớp tên và phiên bản đó.", + "PD-PKG-003": "Bản phát hành đó đã bị tác giả thu hồi. Hãy chọn phiên bản khác.", + "PD-PKG-004": "Bản tải về không khớp mã kiểm tra, nên đã không được cài.", + "PD-NET-001": "PipDock không kết nối được tới danh mục gói.", + "PD-NET-002": "Không xác minh được kết nối bảo mật.", + "PD-NET-010": "Không làm mới được danh mục gói. Bản cũ vẫn dùng được.", + "PD-NET-011": "Sức khỏe mã không tải được công cụ, nên tạm thời chưa dùng được.", + "PD-PRM-001": "PipDock không có quyền ghi vào môi trường này.", + "PD-PRM-002": "Một tệp đang bị chiếm dụng. Hãy đóng thứ đang chạy từ môi trường này.", + "PD-SNP-001": "Không ghi được ảnh chụp, nên không có gì bị thay đổi.", + "PD-SNP-002": "Bản phát hành đó không còn nữa, nên không khôi phục được.", + "PD-SYS-001": "Đường dẫn quá dài với Windows. Hãy bật long paths, hoặc dùng thư mục ngắn hơn.", + "PD-SYS-002": "Không đủ dung lượng trống trên ổ đĩa.", + "PD-HLT-001": "Thiếu một công cụ của Sức khỏe mã. Hãy đồng bộ lại môi trường công cụ.", + "PD-HLT-002": "Một công cụ của Sức khỏe mã dừng với lỗi. Các kết quả khác vẫn dùng được.", + "PD-HLT-003": "Một công cụ của Sức khỏe mã chạy quá lâu và đã bị dừng. Báo cáo chưa đầy đủ.", + "PD-INT-001": "PipDock gặp lỗi nội bộ.", + "PD-ENG-999": "Bộ máy thất bại vì lý do PipDock chưa nhận ra." + } +} diff --git a/ui/src/test/fixtures/codes.json b/ui/src/test/fixtures/codes.json new file mode 100644 index 0000000..bb344cf --- /dev/null +++ b/ui/src/test/fixtures/codes.json @@ -0,0 +1,34 @@ +[ + "PD-ENV-001", + "PD-ENV-002", + "PD-ENV-003", + "PD-ENG-001", + "PD-ENG-002", + "PD-ENG-003", + "PD-RES-001", + "PD-RES-002", + "PD-RES-003", + "PD-RES-004", + "PD-BLD-001", + "PD-BLD-002", + "PD-BLD-003", + "PD-PKG-001", + "PD-PKG-002", + "PD-PKG-003", + "PD-PKG-004", + "PD-NET-001", + "PD-NET-002", + "PD-NET-010", + "PD-NET-011", + "PD-PRM-001", + "PD-PRM-002", + "PD-SNP-001", + "PD-SNP-002", + "PD-SYS-001", + "PD-SYS-002", + "PD-HLT-001", + "PD-HLT-002", + "PD-HLT-003", + "PD-INT-001", + "PD-ENG-999" +]