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:
1 parent
907a653cc5
commit
46c1936650
10 files changed
+182
-21
No files matched your search
@@ -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)
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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({
|
||||
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
Vendored
+34
@@ -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"
|
||||
]
|
||||
Reference in new issue
Block a user