canvas-pilot/docs/development/localization.md

24 KiB
Raw Permalink Blame History

Localization roadmap

Development · Project plan

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 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:

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 for extracting messages and tracking changed translations. mdBook's language setting 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 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. 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. 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 is the user-facing authoring tutorial; the contract 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.