# Localisation AniCraft's interface can be drawn in other languages (ADR 0040). This page is for contributors who write interface text, translators, and whoever builds a release. ## What is translated Everything the shell draws: menus (labels from the command registry, translated as they are drawn), panels, the timeline, Properties, tool options, dialogs, tooltips, status messages, on-stage hints, and the names screen readers announce. Not translated, on purpose: your documents (layer, symbol and scene names), command ids and parameters, the `.anicraft` format, `anicraft-cli`, `serve` and MCP (scripts and agents see the same English everywhere), log output, and the `--help` text. Not yet: engine messages (errors, import reports and the body of confirmations stay English; their titles and buttons are translated), default names of new layers and symbols, and plug-in names. ## Choosing a language **Preferences › Appearance › Language.** *System language* (the default) follows the computer's (the browser's on the web); a language this build has no catalog for falls back to English. A change shows at once. For one run, without saving: `anicraft --lang de` (`--lang auto`, `--lang pseudo`). Which languages a build offers depends on the catalogs it was built with (below). Today craft-i18n has no AniCraft catalog yet, so builds offer English, and the **pseudo-locale** (`--lang pseudo`; listed in Preferences in debug builds) for testing. ## The pseudo-locale Every string accented, about a third longer and in brackets: `Save` → `[Šàvé ~~]`. Use it to check a change: * Text that is still plain English skipped translation. * A label whose `]` is cut off is truncated: give it room, or let it wrap. * Layouts must survive text a third longer (German and Finnish run that long). ```sh cargo run -- --lang pseudo --screenshot shots/pseudo.png cargo run -- --lang pseudo --open prefs --screenshot shots/pseudo-prefs.png ``` ## Writing interface text (contributors) Write English in the code, through the macros (`src/i18n/mod.rs`; in scope everywhere): | You write | You get | |---|---| | `tr!("Save")` | `&'static str` in the interface language | | `tr!("Saved {path}", path = p)` | `String`; placeholders filled after the lookup | | `trn!("{n} layer", "{n} layers", count)` | `String`; the plural form for `count` (CLDR rules), `{n}` filled | | `trc!("menu", "Open")` | a context word, when the same English means two things | | `tr_noop!("Graphite")` in a table, `i18n::t(x)` where drawn | for `const` tables and functions returning English keys | | `i18n::t_cmd(spec.id, spec.label)` | a registry command's label | | `i18n::t(blend.label())` | a lower crate's `&'static str` label | Rules: * **One sentence, one template.** Never glue translated pieces together; word order differs between languages. Name placeholders for what they hold (`{name}`, `{frame}`), never `{}`. * **Counts use `trn!`**, never `if n == 1`. Languages have up to six plural forms. * **Keys stay English.** Translate at the point of display only; anything compared, stored, sent to the engine or used as an egui id stays English. * **Window titles carry their own id** (`egui::Window::new(tr!("…")).id(egui::Id::new("…"))`), so a window keeps its place when the language changes. * **Screen-reader names are text too**: `.named(tr!("…"))`. * Data is not translated: numbers, units, timecode, shortcuts (`platform::shortcut_label`). `cargo test` enforces it: `every_interface_string_goes_through_tr` fails on a prose literal outside the macros (mark one that isn't interface text with `// i18n-exempt: why`), and the accessibility audit fails on a name that the pseudo-locale didn't reach. ## Translating (translators) Translations live in the Craft family's shared repository, [storytold/craft-i18n](https://github.com/storytold/craft-i18n) (MIT OR Apache-2.0), in its format: `locales//anicraft.tsv`, one row per string, `contextEnglishtranslation` (see its `docs/catalog-format.md`). Strings the apps share are in `locales//common.tsv` and already apply to AniCraft; AniCraft's catalog adds the rest and may override a shared row. To get the list of strings: ```sh scripts/i18n-extract.sh # target/i18n/anicraft.tsv: every string CRAFT_I18N_DIR=/abs/path/craft-i18n scripts/i18n-extract.sh # also prints how much of AniCraft each locale already covers CRAFT_I18N_DIR=/abs/path/craft-i18n ANICRAFT_I18N_LOCALE=de scripts/i18n-extract.sh de.tsv # only the strings German doesn't have yet ``` (`scripts/i18n-extract.ps1` on Windows.) Every row is commented out, as craft-i18n's starter files are: delete the `#` and type the translation after the last TAB. Keep `{placeholders}` and a trailing `…`. Then open a pull request in craft-i18n. Follow its clean-room rule: write from the plain meaning of the English, never from another product's translated interface. A language is offered once craft-i18n has its `anicraft.tsv` and it is in `i18n::READY` (left-to-right Latin, Greek and Cyrillic scripts today, and Georgian in builds with its craft-fonts face). ## Building with translations ```sh git clone https://github.com/storytold/craft-i18n ../craft-i18n CRAFT_I18N_DIR="$PWD/../craft-i18n" cargo build --release # an absolute path ``` Without `CRAFT_I18N_DIR` the build is English (and pseudo). `CRAFT_I18N_REQUIRED=1` turns a missing or empty checkout into a build error, for releases. A row the app can't use (bad placeholders, wrong number of plural forms, an unknown `@` context) is skipped with a message on the console, and that string shows in English. ## Scripts and direction egui 0.36 lays text out glyph by glyph, without the Unicode bidirectional algorithm or shaping. So: | Script | Today | |---|---| | Latin, Greek, Cyrillic | Offered when a catalog exists. | | Georgian | Offered when a catalog exists and the build embedded a valid Noto Sans Georgian from craft-fonts (via `CRAFT_FONTS_DIR` or the nearby checkout `build.rs` discovers); hidden only when it did not (`i18n::ready_codes`). | | Chinese, Japanese, Korean | Draw correctly, but need a font the app doesn't bundle (a craft-fonts face), then a `READY` entry. | | Arabic, Hebrew, Persian, Urdu, Kurdish, Dhivehi | Not offered: right to left needs bidi and shaping in egui's text layout, and mirrored widgets. We follow upstream egui rather than fork it. | | Devanagari, Bengali, Tamil, Telugu, Thai, Lao | Not offered: they need shaping. | | Vietnamese | Not offered yet: needs a check that every fallback face has its letters. | Catalogs for these are still embedded (as fallbacks) and pass through the parser, so turning a language on is one line once the shell can draw it.