canvas-pilot/docs/interfaces/language-packs.md

4.7 KiB
Raw Blame History

Canvas Pilot language packs, version 1

Implementation: crates/canvas-pilot/src/language_packs.rs. User instructions and editable downloads: Add a language pack. Example archive.

Archive representation

ZIP, maximum 2 MiB archive bytes and 4 MiB cumulative uncompressed bytes, checked while reading. At most 17 entries: manifest.json plus 1–16 catalog files. Files must be at the archive root. Directories, symlinks, duplicate ZIP names, unexpected files and path separators are rejected. Nothing is extracted. Entry CRC/decompression errors reject the pack. Unsupported ZIP encryption/compression is rejected by zip.

All JSON uses UTF-8. Manifest version is integer 1; unknown manifest/description fields and other versions are rejected. Field order has no meaning.

Field Contract
version Required integer 1
id Pack identifier; 1–63 lowercase ASCII letters, digits or hyphens; no leading/trailing hyphen
languages Required array of 1–16 language descriptions
languages[].locale Unique identifier with the same syntax as id; reserved built-in identifiers and system rejected
languages[].name English display name, 1–160 UTF-8 bytes, nonblank, no control characters
languages[].native_name Native display name, same constraints

Each description requires <locale>.json, a flat object mapping existing English catalog keys to translated strings. At least one message is required. Missing keys fall back to embedded English through rust-i18n; unknown keys reject the whole pack. Values must be nonblank, at most 16,384 UTF-8 bytes, with no control characters other than newline/tab. %{placeholder} names must match the English message's set; unterminated/empty placeholders are rejected. Message order is irrelevant. JSON's ordinary serde map behavior applies: repeated object keys resolve to the last value; authors must use unique keys. No geometry, numbers, project data or precision fields are part of this format.

Version 1 supplies no fonts, language inheritance, executable plugins, network URLs or automatic downloads. The built-in font repertoire determines rendering. No override of built-in catalogs is allowed. Catalogs use an internal pack: namespace in the runtime rust-i18n backend; the manifest contains only uk, etc. Catalogs are loaded into memory, not read on every label render. Selection is explicit per egui context, never a process-global current language.

Installation and persistence

Installation validates all entries and locale collisions before writing. A temporary file in the destination directory is flushed and persisted without clobbering to <settings-parent>/language-packs/<id>.zip; only then are languages registered. The source ZIP is retained. The installed ZIP preserves original bytes exactly; there is no re-export or lossy normalization. A pack containing any already-loaded locale is rejected in full. An existing destination file is never replaced, including an invalid one.

Startup reads at most 32 .zip files from that directory, sorted by path when within the limit. If there are more, the first 32 discovered entries are considered, then sorted, and an error is reported; users must reduce the count. Invalid packs are skipped with errors. The first valid pack supplying a locale wins; a later colliding pack is rejected in full. Installation also refuses a 33rd ZIP. Startup is offline. Manual removal/replacement takes effect after restart.

The settings v13 contract stores an installed choice as "language": {"pack": "uk"}. Missing packs retain this preference but render in English, with an unavailable indicator in the selector. Installing the missing pack re-applies that preference. Existing language confirmation, cancellation and 20-second rollback apply; installation alone does not select another language. System default resolves only built-in locales. Project/recovery documents contain no language-pack settings; device/export behavior is unchanged.

Compatibility and evidence

Pack v1 is supported from application v0.9.7. Built-in English keys define the accepted catalog vocabulary for the running version; removed/renamed keys require pack updates. Adding an English key does not break partial packs. Older applications lack pack loading and reject settings v13. Tests cover ZIP/source equality, install/restart/removal, fallback, placeholder substitution, rejected archives, non-overwrite, settings migration, confirmation rollback and unchanged project data. Example catalog characters are checked against the bundled fonts. Example wording is unreviewed machine translation, not linguistic acceptance.