feat(i18n): a one-liner for every catalog code, in both locales

**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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent 907a653cc5
commit 46c1936650
10 files changed
+182 -21

No files matched your search

+5 -3
View File
@@ -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)
+12
View File
@@ -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> {
crate::errors::Code::ALL.to_vec()
}
/// Every fixture, as `(file name, contents)`.
///
/// # Errors
@@ -302,6 +313,7 @@ pub fn ipc_fixtures() -> serde_json::Result<Vec<(&'static str, String)>> {
("guard_report.json", render(&guard_report())?),
("snapshot_list.json", render(&snapshot_list())?),
("rollback_preview.json", render(&rollback_preview())?),
("codes.json", render(&codes())?),
])
}
+4 -2
View File
@@ -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
+37
View File
@@ -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<string, string> }).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<string, string> }).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<string, string> }).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.
+18 -2
View File
@@ -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({
-7
View File
@@ -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."
}
}
+36
View File
@@ -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."
}
}
-7
View File
@@ -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."
}
}
+36
View File
@@ -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."
}
}
+34
View File
@@ -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"
]