mirror of
https://github.com/storytold/lightcraft.git
synced 2026-10-27 11:37:13 -06:00
Brandon ThomasandClaude Opus 5.5
313c555b50
Restore main's compile-checked formatting, generalised to N catalogs: build.rs
writes one tr_format! arm per English message that matches on the active
language and calls format! with that language's translation (English is the
fallback arm). The runtime substitution dropped format specs ({:.1}, {:+},
{:.0}%), e.g. the smart-preview size and the merge progress percentage.
- formats catalogs use main's convention again ({0}/{1} for reordering, {:.0}
to consume an unused plural suffix); zh-hans converted, with the size and
percentage placeholders fixed by hand
- build.rs: auto-discovers locales/*-formats.json, validates the code
(^[a-z]+(-[a-z]+)*$), fails when the catalogs' keys differ, and reruns
when the locales directory changes
- zh-hans: translate the strings main added since the PR branched
- test: precision, sign and reordered positional values survive in every
language
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
# Localization
|
|
|
|
The interface ships in the language it is written in (English) plus every language in the table in
|
|
`crates/ui-egui/src/i18n.rs`. Today that is English, Simplified Chinese (`zh-hans`) and Japanese
|
|
(`ja`). This file is the reference for **adding or maintaining a language**; the per-language notes
|
|
are in [`localization-zh-hans.md`](localization-zh-hans.md) and [`localization-ja.md`](localization-ja.md).
|
|
|
|
## Adding a language
|
|
|
|
1. **Translate the two catalogs.** Copy `locales/ja.json` and `locales/ja-formats.json` to
|
|
`locales/<code>.json` and `locales/<code>-formats.json`, then translate the values. Keys are the
|
|
English source strings and must stay byte-for-byte identical — `cargo test -p lightcraft-ui-egui
|
|
i18n::tests` fails on a missing, extra or empty entry.
|
|
2. **Add the table entry** in `crates/ui-egui/src/i18n.rs`:
|
|
|
|
```rust
|
|
language_table! {
|
|
En, "en";
|
|
ZhHans, "zh-hans", "简体中文", "Hans", include_str!("../locales/zh-hans.json");
|
|
Ja, "ja", "日本語", "Jpan", include_str!("../locales/ja.json");
|
|
}
|
|
```
|
|
|
|
The fields are the BCP-47 code (also the settings-file value), the **endonym** shown in the
|
|
Language menu, the ISO 15924 script (`Latn`, `Jpan`, `Hans`, `Hant`, `Kore`…), and the embedded
|
|
catalog. `build.rs` picks up `<code>-formats.json` by name, so the macro and the format lookup
|
|
follow automatically — nothing else in the UI needs to change. The menus, the settings row, the
|
|
keyboard-shortcut sheet and the control channel all read the table.
|
|
3. **Make sure the glyphs exist.** The script drives which craft-fonts faces the UI installs: a
|
|
language whose script has no face in the build shows boxes (the test says so instead of failing).
|
|
Fonts live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts), never here; a
|
|
missing face is added there, not worked around in this repository.
|
|
4. Run `cargo xtask ci` (it includes `fmt`, `clippy`, the tests, `parity` and the wasm check).
|
|
|
|
## How a message is found
|
|
|
|
`tr("Exposure")` looks the English label up in the active language's catalog and returns the source
|
|
text unchanged when there is no entry; `tr_format!` handles text with runtime values. Both are
|
|
presentation-only: command ids, file names and user-entered metadata are never translated.
|
|
|
|
`tr_format!` is generated by `crates/ui-egui/build.rs`: one arm per English message, which formats
|
|
the active language's translation with `format!` (English is the fallback arm). Every catalog's
|
|
format string is therefore checked by Rust against the call site's own arguments:
|
|
|
|
```rust
|
|
tr_format!("Added {n} photo{} to “{}”", if n == 1 { "" } else { "s" }, album, n = n)
|
|
```
|
|
|
|
- A translation is an ordinary Rust format string over the same arguments. Refer to named values by
|
|
name (`{n}`) and to positional ones by index when the word order changes (`{0}`, `{1}`):
|
|
`"已将 {n} 张照片添加到“{1}”{0:.0}"`. Keep the source's spec (`{:.1}`, `{d:+}`, `{:.0}%`).
|
|
- `format!` rejects an unused argument, so a value a language does not need — the English plural
|
|
suffix (`"s"` / `""`) — is consumed as `{:.0}` (a string at precision 0 prints nothing).
|
|
- Every formats catalog carries the same messages (`build.rs` fails the build otherwise), and a
|
|
`tr_format!` call whose message is in no catalog does not compile: add it to every
|
|
`*-formats.json` file.
|
|
|
|
## Testing and looking at it
|
|
|
|
```sh
|
|
cargo test -p lightcraft-ui-egui i18n::tests # catalogs, keys, placeholders, commands
|
|
CRAFT_FONTS_DIR=../craft-fonts cargo test -p lightcraft-ui-egui i18n::tests # + glyph coverage
|
|
```
|
|
|
|
The glyph tests are skipped without `CRAFT_FONTS_DIR` (there are no CJK faces to check then).
|
|
To look at a language, render it headless:
|
|
|
|
```sh
|
|
LIGHTCRAFT_LANGUAGE=zh-hans lightcraft-cli snapshot --demo --script tour.jsonl -o out.png --size 1600x1000
|
|
```
|
|
|
|
or, with the app running (`--control 7980`), run the language command
|
|
(`engine.execute {"command": "app.language.zh-hans"}`) and take a screenshot.
|
|
|
|
## Language codes and settings
|
|
|
|
The settings file stores the BCP-47 code, never the Rust variant name, so a language can be renamed
|
|
in code without invalidating anyone's saved preference. `LIGHTCRAFT_LANGUAGE` accepts what a system
|
|
locale looks like (`zh_Hans`, `zh-CN`, `en_US`, `ja_JP.UTF-8`) and falls back to the base language
|
|
when a region has no dedicated entry.
|