canvas-pilot/docs/development/localization.md

374 lines
24 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Localization roadmap
[Development](README.md) · [Project plan](../canvas-pilot/plan.md)
## Status
The localization stretch goal is **done for the accepted current scope** as of
2026-11-18. The broader checklist below is retained as optional expansion and
maintenance guidance, not outstanding acceptance for that completed goal.
Translation provenance and review limitations still apply.
## Current pilot: French quick start only
The [French quick start](../canvas-pilot/guide/fr/quickstart.md) is based on machine translation,
requested as a small first step. French interface terminology was accepted on
2026-11-16; the chapter now follows those French control labels and uses three
fresh French screenshots. English remains authoritative. This records approval
of UI wording, not an independent editorial review of the adapted chapter.
The application also has eleven translated UI previews (see below). The rest of the manual remains English, with explicit fallback links.
For this one-chapter pilot, use translated Markdown in `guide/fr/` and the existing
mdBook build. The summary and reciprocal chapter links expose the language choice;
a `lang="fr"` wrapper identifies French content while the book navigation stays
English. The warning appears in the chapter and print view. Existing assets and
English URLs remain unchanged. Do not duplicate the whole book for this pilot.
The translation comment records the English source commit. When updating the English
quick start, compare it with that revision, update the French text (or visibly mark
it outdated), and advance the recorded revision only after translating the changes.
For the latest aligned source revision:
```sh
git diff daa8975 -- docs/canvas-pilot/guide/quickstart.md
```
The French chapter additionally explains language selection and uses French
controls and images. Keep its machine-translation origin and English-authority
notice visible. Build/link checks are not linguistic verification. Run the pinned manual build after
updates and check French accents, links, screenshots, search and print output.
For a larger translation effort, evaluate
[mdbook-i18n-helpers / gettext](https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md)
for extracting messages and tracking changed translations. mdBook's
[language setting](https://rust-lang.github.io/mdBook/format/configuration/general.html)
sets book language metadata; it does not manage translation freshness. Separate
language builds and a full language selector remain future work. Do not introduce
both Markdown and gettext as competing maintained translation sources.
The checklist below describes that broader future work. The later reviewed-book
publication criteria do not describe the current status of the whole manual.
The accepted French interface vocabulary does not imply review of other languages.
## Application implementation
The desktop UI uses [rust-i18n](https://docs.rs/rust-i18n/) with embedded English, French, Japanese, Simplified Chinese, Spanish, Ancient Greek,
Esperanto, European Portuguese, Nepali, Thai, Hindi and Toki Pona JSON catalogs in `crates/canvas-pilot/locales/`. `sys-locale` obtains the desktop
language. Built-in catalogs remain embedded. Runtime ZIP packs use the rust-i18n backend
extension and serde JSON parsing; no network translation service is involved. The lockfile pins the dependency versions.
`src/localization.rs` only resolves the supported language preference and passes an
explicit locale to rust-i18n. Each egui context holds its own resolved language;
there is no process-global `set_locale`, avoiding cross-window/test interference.
Built-in catalogs compile into the binary, so portable releases need no additional
files for those languages. Optional packs persist beside user settings.
The build script watches `locales/`, including catalog-only edits and newly added
files; translators do not need to touch Rust code to trigger a rebuild.
Settings v10 adds `ja`, `zh-CN`, `es`, `grc` and `eo` to v9’s `system`, `en`, `fr`.
Versions 1–8 migrate with System default; v9 preserves its language and all other
preferences. Unknown old language values are rejected rather than reinterpreted. The always
visible **Language / Langue** selector at the top of Settings previews immediately,
then requires confirmation within 20 seconds. Question and acceptance use the new
locale; cancellation and an additional countdown use the previously displayed
locale. Escape and timeout roll back; settings writes retain the old choice until
confirmation. The transient preview is not project or settings data.
Project, export, clipboard and device contracts are unchanged. Every non-English
language has the same preview status, not a human-reviewed complete translation: technical diagnostics, some advanced
controls, device-supplied labels and native file dialogs can still be English.
Native dialogs follow the OS, not this application's preference.
### Fonts and script support
The application embeds full Noto Sans 2.015 (Latin, polytonic Greek and Cyrillic)
and Noto Sans CJK 2.004 (including Japanese and Chinese). The collection is embedded
once, using face 0 for Japanese and face 2 for Simplified Chinese. This preserves
regional Han letterforms and supports arbitrary names beyond catalog characters.
Noto Sans leads proportional text; CJK and existing symbol/emoji fonts provide
fallbacks. Monospace keeps its existing first choice with Noto fallbacks. Language
selection rebuilds the font definitions once per change, never per frame.
See the [font provenance and checksums](../../crates/canvas-pilot/assets/fonts/README.md).
The SIL Open Font License is included with the fonts and embedded in the executable,
available in Settings → Files & settings → Font licenses. The full CJK collection
adds about 19 MiB to the embedded assets; it is deliberately not reduced to only
current translations, which would break future text and imported names.
Tests check every catalog character, every language endonym, mixed Latin/CJK/Greek
strings, both font families and the selected CJK face. Greek catalog text uses NFC
precomposed accents for this renderer. These checks establish glyph coverage, not
human translation review or general support for all complex scripts.
The application now uses egui/eframe 0.35, the smallest released upgrade with
HarfRust shaping. The 0.37 API migration was evaluated, but is unnecessary for
these script labels; 0.35 retains the existing bounded file-import representation.
The migration adopts root-Ui panels, explicit popup close behavior and the updated
font/layout APIs. Clipboard and links remain enabled by eframe 0.35's integration.
The dependency requires Rust 1.92 or newer.
Full Noto Sans Devanagari 2.007 and Noto Sans Thai 2.002 are embedded alongside the
existing fonts, with provenance and OFL notices. No OS font installation, private-use
encoding, romanization or pre-shaped Unicode rewriting is needed. Portuguese is
European Portuguese (`pt-PT`); Brazilian system locales fall back to English.
Toki Pona uses Latin spelling; sitelen pona is outside this implementation.
Settings v12 adds `pt-PT`, `ne`, `th`, `hi`, `tok`, preserving v11 preferences and
rejecting unknown or out-of-version values before migration.
The new catalogs translate everyday controls, language confirmation, common editing
help and file-replacement warnings. Some longer explanations and advanced/device
controls deliberately remain in English, as do uncatalogued diagnostics. Catalog
key parity does **not** imply translation completeness or linguistic review.
### Complex-script validation
`cargo run --example text_shaping` is an explicitly invoked, offline diagnostic.
It shares the application's fonts/catalogs and provides labels, narrow wrapping,
mixed scripts and editable samples, without user settings or device access.
Validation for v0.9.6 includes actual egui conjunct formation (`क्ष`), pre-base
vowel placement (`कि`), Thai mark stacking (`กิ้`), wrapping, Unicode paste,
selection, copy and cursor traversal. The full language-switch regression uses all
choices and preserves project bytes, drafts and clipboard geometry. Versioned
settings tests cover old-language rejection and migration without preference loss.
Project opening/recovery preserves language, display scales and pending confirmation;
the native recovery walkthrough exposed a reset that now has regression coverage.
Native X11 screenshots of Nepali and the typography probe were compared visually
against Pango using the same installed Noto fonts. This is rendering evidence,
not native-speaker approval. Scripted native mouse clicks opened Settings, switched
from Nepali to Thai, confirmed the bilingual prompt and verified the saved choice.
Temporary screenshots and profiles stay outside Git. The final default suite passed
440 tests (two manual checks ignored); all-features and restricted suites each
passed 434 (one manual check ignored). Formatting, both Clippy configurations,
rustdoc with warnings denied and the pinned manual build passed. Whole-application
line coverage was 91.41%, above the 75% floor.
Known remaining renderer limits:
- In egui 0.35, Thai `ำ` can expand into extra glyphs while cursor bookkeeping
still assumes one glyph per character. End followed by Backspace can leave the
last character unchanged. Plain paste and select-all/copy preserve the original
Unicode; translated labels render correctly. Do not claim fully correct Thai
text editing or fix this by rewriting user content. The diagnostic includes
`น้ำ` to keep the issue reproducible.
- Thai wrapping is not verified against dictionary-based word segmentation.
- Cursor movement can step through code points within a shaped cluster; testing
does not establish native-quality input-method composition on all operating
systems. Native IMEs and linguistic review remain manual acceptance.
All available languages are normal choices, without joke labels or special modes.
### Operator terminology and content boundaries
Localization is cosmetic: translate interface instructions, never project content.
Keep all titles and default names/values in their original language, including newly
created layers, folders and example content. Exports, clipboard payloads, generated
artwork, device values and serialization remain independent of the selected language.
For French, use **ratio**, not “rapport”, for aspect-ratio controls. Generic editor
terms may use **écran** and **calque**; do not force these translations onto names
shown by the switcher. Preserve the English MIDRA/WebRCS control and option names
operators need to match on their device, including **Content ratio**, **Transform to**,
**Layer fill option**, **Native**, **Signal**, **Custom**, **Layer setting**,
**Centered**, **Cropped**, **Full screen / Fullscreen**, **1:1**, **Input settings**,
**Global settings**, **Preview**, **Program** and **Blanking**. Retain the spelling
used by the corresponding control. Translate surrounding explanations; an optional
French explanation should accompany, rather than replace, the English device name.
Apply the same principle to other adapters' native terminology.
### Maintaining UI messages
- Use stable descriptive keys and complete messages in `locales/en.json` and
`locales/fr.json`. Keep existing keys when polishing wording; do not derive keys
from runtime text or translate arbitrary document/device names.
- Call `tr(ui.ctx(), "ui.message-key")` for simple text. It delegates to rust-i18n.
For values, call `rust_i18n::t!("key", locale = localization::locale(ctx), name = value)`
and convert to an owned string for egui. Use named `%{name}` placeholders, never
concatenate grammatical sentence fragments. Numeric summaries should avoid
English-only singular/plural assumptions; evaluate plural-aware messages before
adding inflected count-dependent wording.
- Update all twelve catalogs together. English is the fallback; catalog tests check key and
placeholder parity and direct UI references. Do not translate serialization keys,
protocol values, keyboard shortcut identities, project names, user input or IDs.
- Give windows and controls stable IDs separate from translated display text.
Preserve semantic action dispatch; never match translated button text to decide
what operation to execute.
- Existing diagnostic strings remain English until they can be modeled as structured
errors with localization at display time. Do not perform string replacement on
errors from devices, converters or external libraries.
- Follow the Rust gates in [CI](ci.md). Localization tests cover regional fallback,
independent contexts, catalog completeness, settings migrations and interactive
switching/restart without changing project bytes, drafts or device-send state.
A layout regression test checks that language selection and Close remain visible
in every section at 1000 × 720, in every language. French Settings and menus were
also visually checked in the Linux desktop app at normal and minimum sizes.
Native Windows/macOS visual acceptance and human language review remain pending.
The expanded catalogs also passed native Linux visual checks for Japanese,
Chinese, Spanish, Esperanto and polytonic Greek at 1000 × 720. Automated switching
preserves serialized project and clipboard data, settings persist all language
choices. That earlier implementation recorded 91.01% whole-application coverage;
current validation is recorded above.
- Technical validation does not constitute human linguistic review. Keep preview
status until terminology and actual workflows have been reviewed.
The broader checklist below remains the roadmap for full localization, review and
additional languages; these foundation tasks do not mark the whole goal complete.
## 1. Localize the book
### Prepare the translation workflow
- [ ] Confirm the first language, its reviewer and the scope of its initial release.
Include installation, quick start, format matrix, template catalog and advanced
chapters. Developer contracts and historical changelogs may stay in English,
clearly identified when linked from a translated page.
- [ ] Review source chapters for stale labels, ambiguous instructions and duplicated
prose before translating them. Translate the canonical chapter sources, not
READMEs, generated HTML or a second copy of the manual.
- [ ] Establish a shared glossary: layer, source/input, crop, fit, mask/blanking,
visible box, screen, Preview/Program, load, send and snapshot. Keep product names,
extensions and actual device identifiers unchanged. Record terms best left in
English so the book and application use the same vocabulary later.
- [ ] Choose one translation representation: translated Markdown chapters with
matching paths, or extracted message catalogs. Pilot a short chapter and the
feature matrix before deciding; document the workflow and avoid maintaining both.
- [ ] Record the source revision for translations and flag changed or missing
passages for review. Define who reviews updates and what counts as ready to publish.
### Build and publish translated books
- [ ] Extend `scripts/manuals.py` to stage each language with its own title,
language metadata, navigation and output directory. Retain the existing English
URLs; use language subpaths for new translations under `/manuals/canvas-pilot/`.
- [ ] Add a visible language selector that preserves the current chapter when
possible. Provide an explicit fallback to English for untranslated chapters;
do not silently label English content as translated.
- [ ] Resolve chapter links and section anchors within the chosen language, with
explicit English links where no translation exists. Check contents, search,
print view, page titles and image alt text in each build.
- [ ] Reuse the existing template files, ZIP, icons and applicable screenshots.
Translate the catalog labels and instructions, without creating language-specific
copies of identical downloads. Preserve existing client-facing download URLs.
- [ ] Translate captions and alt text. While screenshots and the walkthrough use English, keep their
exact English control labels alongside translated instructions. Identify the
language shown in screenshots; replace or supplement them after app localization.
- [ ] Extend publication and cleanup tests to cover all language directories while
protecting other books and the shared manuals index. Publish only reviewed
languages and make translation availability visible from the English book.
### Book acceptance checklist
- [ ] Review the first translation for natural language and consistent terminology,
especially crop/mask differences and device-write instructions.
- [ ] Follow installation, first layout, template selection and import/export from
the translated instructions, using the application version described by the book.
- [ ] Build every published language with the pinned mdBook version. Check all
local links, anchors, pictures, downloads, print pages and language-switch paths.
- [ ] Check narrow-screen tables, long headings, accented text, search results and
the format matrix's emoji/numbered notes in the rendered book.
- [ ] Document how to propose a translation, update it after an English edit and
report a translation error. Mark the first language ready only after review.
## 2. Localize the application
Begin after the book workflow and glossary have been validated.
### Separate display language from application data
- [ ] Inventory visible text: menus, dialogs, toolbar tooltips, keyboard help,
properties, presets, empty states, status messages, progress, errors, file
filters, recovery/overwrite prompts, device review and connection controls.
Include launcher text where relevant. Generated SVG labels and export artwork
remain in their original language as document content.
- [ ] Choose a small Rust-compatible localization mechanism with stable message
keys, named placeholders, plural support and English fallback. Trial it in one
settings panel and an error dialog before migrating the rest of the UI.
- [ ] Keep complete sentences in catalogs; avoid concatenating translated fragments.
Separate raw device/converter diagnostics from translated explanations, retaining
technical detail useful for troubleshooting.
- [ ] Keep project field names, schema markers, adapter identifiers, protocol paths,
enum values, file extensions and numeric serialization language-independent.
Language changes must not alter geometry, project compatibility or device writes.
- [ ] Protect copy/paste: `gui.rs` currently emits labels such as `Horizontal:` and
`Crop zoom:` that `import.rs` parses. Keep this exchange representation stable,
or design and test a versioned language-independent payload before translating
its human-readable presentation. Preserve existing clipboard samples.
- [ ] Preserve existing layer/folder names, imported names, custom presets and
device-provided labels. New-project titles, example names and default values also
remain in their original language; never rename content when switching languages.
### Add language preferences and readable UI
- [ ] Add an application language preference with **System default**, explicit
supported languages and English fallback. Define region matching and the
behavior when the saved language is unavailable.
- [ ] Store the preference in application settings, not in projects. Update the
settings contract, migration examples and regression tests if its schema changes.
- [ ] Define whether language changes apply immediately or need restart. Preserve
unsaved edits and active operations; switching language must not start a device
action or discard a draft.
- [ ] Define decimal entry and formatting for comma-decimal locales. Keep file
exports, clipboard data and device numbers in their documented invariant form;
reject ambiguous input rather than silently changing a measurement.
- [ ] Verify font coverage for each shipped language and include required font
licensing. Check emoji, accents, units, shortcuts and fallback glyphs.
- [ ] Make controls tolerate longer text: buttons, narrow sidebars, combo boxes,
tabs, table headers, tooltips and status bars. Test a deliberately expanded
pseudo-language before relying on short English strings.
- [ ] Point Help links to the selected language's book with English fallback.
Refresh localized screenshots only after terminology and layout are stable.
### Translate and validate
- [ ] Translate the agreed UI scope using the book glossary; review destructive
actions, overwrite/recovery prompts and Preview/Program warnings carefully.
- [ ] Add catalog checks for missing/unused keys, placeholder mismatches, malformed
messages, plural cases and fallback behavior. Define a completeness threshold
before a language appears in the language selector.
- [ ] Test settings round trips, missing-language fallback and language switching
with pending edits, recovery state and disconnected devices.
- [ ] Test copy/paste between languages and confirm saved projects and exchanges
remain interoperable. Verify locale-independent numeric output and decimal entry.
- [ ] Check supported desktop platforms, display scaling, small windows and long
translations. Keep a short manual walkthrough for each shipped language.
- [ ] Run the existing default/restricted Rust gates and whole-application coverage;
add meaningful localization regression tests without duplicating every label.
- [ ] Review the matching book and application together, record translation status
in release notes, and assign ongoing review of newly added messages.
## Later, when a language needs it
- [ ] Evaluate right-to-left layout, bidirectional text and text shaping before
advertising a language that requires them; font coverage alone is insufficient.
- [ ] Add translated video captions and transcripts when the planned videos exist.
- [ ] Consider a hosted translation platform only when contributor volume makes
the repository-based workflow difficult to maintain.
## Runtime language-pack example (v0.9.7)
Settings now imports bounded ZIP packs and lists their languages immediately. The
[manual walkthrough](../canvas-pilot/guide/language-packs.md) is the user-facing
authoring tutorial; the [contract](../interfaces/language-packs.md) owns schema,
limits, persistence and compatibility. The example adds Ukrainian and Bhojpuri,
39 messages each, without adding either language to the compiled enum/catalogs.
The same built-in fonts cover both examples. This demonstrates external catalogs;
external font packs and reducing the release size remain future work.
Settings v13 keeps built-in strings and adds an installed-language object. Missing
packs preserve the requested language while falling back to English. Catalogs
are registered with rust-i18n's runtime backend; the current locale remains per
context. Unknown keys/placeholders, malformed ZIPs and collisions reject the whole
installation. Existing files and projects are preserved. Example translations are
partial and unreviewed.
Validation: default Rust suite 444 passed / two manual checks ignored; all-features
and restricted suites each 438 passed / one manual check ignored. Formatting,
Clippy in both configurations and warnings-denied rustdoc passed. Whole-application
line coverage: 91.38%. The pinned manual build validates 24 HTML pages and the new
ZIP/JSON downloads. Scripted native X11 clicks scrolled to both installed languages,
selected/confirmed Ukrainian and inspected Bhojpuri with the previous-language
cancellation prompt. Saved settings contained the installed locale in v13 form.
The desktop portal file chooser was unavailable on the isolated display; archive
installation is covered by filesystem tests, and the native walkthrough used the
manual-copy/startup discovery path. Windows/macOS native chooser acceptance remains
unverified. Temporary screenshots/profiles are outside Git.