141 lines
8.6 KiB
Markdown
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.
|