55 lines
3.3 KiB
Markdown
55 lines
3.3 KiB
Markdown
# Translating FigCraft
|
|
|
|
FigCraft's interface strings live in one TOML catalog per language in
|
|
[`crates/ui-egui/locales/`](../crates/ui-egui/locales). The build bakes every catalog into the
|
|
binary (desktop and web); nothing is read at run time. Preferences ▸ Language picks the language
|
|
(System follows the OS, or the browser on the web) and the interface switches at once. `pref.language
|
|
{language}` does the same from the CLI, MCP and the control channel.
|
|
|
|
## The catalogs
|
|
|
|
- **`en.toml`** lists every key. A key is the English text as the code writes it, so the code stays
|
|
readable: `tr("Fill")`, `trf("Delete {name}?", &[("name", &name)])`, `trn("{n} layers", count, &[])`.
|
|
Values equal their keys except plurals, which give both forms:
|
|
`"{n} layers" = { one = "{n} layer", other = "{n} layers" }`.
|
|
- **`es.toml`** and other languages translate the same keys under `[ui]`, plus command labels by
|
|
command id under `[commands]` (the Actions palette, the shortcuts panel and the menus) and, under
|
|
`[menu]`, the few menu items the main menu words differently from the command (the Select matching
|
|
submenu's "Fill" for "Select same fill"). Command ids, the CLI, MCP and control-channel output stay
|
|
English.
|
|
- `[meta] name` is the language's own name (the picker shows it untranslated); `[meta] status` marks
|
|
a draft (the Preferences window says so).
|
|
|
|
A key a catalog lacks shows its English text, so a partial catalog is safe to ship.
|
|
|
|
## Adding a language
|
|
|
|
1. Copy `crates/ui-egui/locales/es.toml` to `<code>.toml` (a BCP 47 code: `fr`, `pt-BR`, `ja`) and
|
|
set `[meta] name` and `status = "draft — needs native review"`.
|
|
2. Translate every value; keep the keys. Keep `{placeholders}` exactly, "…" where English has it,
|
|
brand names and keyboard glyphs. English labels of commands: `figcraft-cli commands`.
|
|
3. Plurals: give `one` only if the language has a singular form (Japanese, Korean and Chinese give
|
|
only `other`). `trn` picks `one` for a count of 1; a language with other rules (French: 0 and 1)
|
|
needs its rule in `plural_one` in [`crates/ui-egui/src/i18n.rs`](../crates/ui-egui/src/i18n.rs).
|
|
4. To require full coverage, add the code to `COMPLETE` in
|
|
[`crates/ui-egui/src/i18n_tests.rs`](../crates/ui-egui/src/i18n_tests.rs).
|
|
5. Run the check and look at the panels in the app (longer words must fit the right panel):
|
|
|
|
cargo test -p figcraft-ui-egui i18n
|
|
|
|
The check fails on keys the code uses that `en.toml` lacks (it prints the lines to paste), keys no
|
|
code uses, unknown command ids, placeholders that don't match English, and, for complete languages,
|
|
anything untranslated. Machine-drafted catalogs stay marked as drafts until a native speaker has
|
|
reviewed them.
|
|
|
|
## Adding strings in code
|
|
|
|
Wrap every string a user sees or a screen reader hears: `tr` for plain text, `trf` for `{named}`
|
|
placeholders, `trn` for counts, `tr_noop` for literals in `const` tables that are looked up later
|
|
with `tr(label)`. The key must be a string literal as the first argument (the check reads the
|
|
source). Don't wrap ids, command ids, JSON, log messages, file extensions or document content. Then
|
|
add the key to `en.toml` and to each complete language.
|
|
|
|
Labels from the engine and document crates (tool names, blend modes, easing curves…) are looked up
|
|
at display with `tr(x.label())`; they are listed in `dynamic_labels` in `i18n_tests.rs`.
|