Follow-up to outside PR #486: restores the untouched lines rustfmt rewrapped (READY and the test lists other tracks edit), renames the Hebrew test for what it checks (never offered yet), checks Georgian still draws with the Hebrew face behind it, adds the ATTRIBUTION row, and words the docs for what the face does today: Hebrew letters in names, not an interface language.
7.0 KiB
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).
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!, neverif 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 (MIT OR Apache-2.0), in its
format: locales/<locale>/anicraft.tsv, one row per string, context<TAB>English<TAB>translation
(see its docs/catalog-format.md). Strings the apps share are in locales/<locale>/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:
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, plus Georgian in builds with its craft-fonts face).
Building with translations
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). |
| Hebrew | Not offered yet: right to left needs bidi in egui's text layout, and mirrored widgets. Prepared so far: builds with craft-fonts embed Noto Sans Hebrew (Hebr) as a fallback face, so Hebrew letters in names draw instead of empty boxes (still in typing order, not yet right to left); the legacy code iw is read as he (iw_IL from Java and older systems); and i18n::is_rtl_code answers which codes are right to left, script subtag first. |
| Chinese, Japanese, Korean | Draw correctly, but need a font the app doesn't bundle (a craft-fonts face), then a READY entry. |
| Arabic, 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.