Files
AniCraft/docs/localisation.md

6.6 KiB
Raw Permalink Blame History

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!, 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 (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, and 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).
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.