canvas-pilot/docs/development/localization.md

141 lines
8.6 KiB
Markdown

# Localization roadmap
[Development](README.md) · [Project plan](../canvas-pilot/plan.md)
Deliver the translated **book first**, then the **application**. This is a task
list, not an announcement of available languages. Keep detailed completion status
here and the overall milestone in the project plan.
English remains the source language. French is the suggested first translation
for proving the workflow; confirm the initial languages before starting translation.
Keep the process small enough to maintain without a dedicated translation service.
## 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 the app is English-only, keep its
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 generated SVG labels, export artwork and launcher text where relevant.
- [ ] 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. Decide which new-project example names may be localized;
never rename existing 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.