Merge pull request #112 from Mithril-3d/feat/i18n-support

feat: add extensible offline localization with Japanese UI

docs/control-protocol.md

@@ -50,7 +50,7 @@ Commands never open dialogs when run this way. `solvecraft-cli commands` prints
 | `ui.home` | `open?`: bool; `sample?`: index | the start page: show or hide it, open a built-in sample (once built); returns `open` and the recent designs |
 | `ui.shortcut` | `command`, `key?`, `replace?` | a command's key, or rebinds it (`""` clears; a key another command uses is refused unless `replace`) |
 | `ui.help` | `item?`: `about`, `shortcuts` (read only), `report` (copies diagnostics) | the version, commit, build date and diagnostic text |
-| `ui.prefs` | any of `default_units`, `nav` (`fusion`, `solidworks`, `inventor`, `alias`, `tinkercad`), `zoom_reverse`, `zoom_to_cursor`, `orbit_cursor`, `look_at_anim`, `look_at_speed`, `msaa`, `length_decimals`, `angle_decimals`, `theme` (`dark`, `light`, `system`), `ui_scale`, `up_axis` (`z`, `y`), `offer_stand_up`; `open` (a page: General, Navigation, Keyboard Shortcuts, Design, Graphics, Sketch, Selection) opens the Preferences dialog there; `button`: `ok`, `cancel`, `apply`, `defaults`; `stand_up: true` stands up a just-opened Y-up file | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `dark` and `stand_up_offer` |
+| `ui.prefs` | any of `default_units`, `nav` (`fusion`, `solidworks`, `inventor`, `alias`, `tinkercad`), `zoom_reverse`, `zoom_to_cursor`, `orbit_cursor`, `look_at_anim`, `look_at_speed`, `msaa`, `length_decimals`, `angle_decimals`, `theme` (`dark`, `light`, `system`), `language` (`en`, `ja`; see [localization](localization.md)), `ui_scale`, `up_axis` (`z`, `y`), `offer_stand_up`; `open` (a page: General, Navigation, Keyboard Shortcuts, Design, Graphics, Sketch, Selection) opens the Preferences dialog there; `button`: `ok`, `cancel`, `apply`, `defaults`; `stand_up: true` stands up a just-opened Y-up file | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `dark` and `stand_up_offer` |
 | `ui.capture` | `action?`: `capture`, `revert`, `cancel` | answers the Capture Position question (asked when a command starts or the design is saved while components were moved without capturing); without `action`, what waits |
 | `ui.window` | `action`: minimize, maximize, restore, toggle, close | what the title bar's caption buttons do (on Windows and Linux the application bar is the title bar); close asks about unsaved designs first |
 | `ui.agent_cursor` | `show` (bool), `speed`: a number from 1 to 5 (times the normal speed) or `"instant"` (no animation: the command runs at once and the pointer jumps to where it acted), `follow_camera` (bool); all optional | the settings. While the cursor is shown, `engine.execute` first glides to the command's toolbar button and to each pick, then runs and replies; later requests wait their turn. `"animate": false` on a call skips it |

docs/localization.md

@@ -0,0 +1,41 @@
+# UI localization
+
+SolveCraft embeds its translations and works offline. English and Japanese are currently
+registered in `crates/ui-egui/src/i18n.rs`. Adding a language requires an embedded catalog and
+one registration there; the preferences selector and validation use the same registry.
+
+## Messages
+
+`crates/ui-egui/src/locales/en.json` defines stable message IDs and English fallback text.
+Keep IDs when changing wording. Other catalogs use the same IDs; missing messages fall back
+to English. Use `app.tr("ui.preferences")` for static messages and
+`Locale::format` for full sentences with named placeholders. Translate the entire sentence,
+including punctuation, so a translator can reorder its arguments. Placeholder values are
+inserted literally, even if a document name contains braces.
+
+The English-label adapter (`app.tr_label`) supports existing engine and UI tables. It maps
+display text to a message ID, then uses the same catalog lookup. New UI messages should use
+stable IDs directly. The adapter does not change command IDs, model names, or scenario handles.
+When a table's English wording changes, update the corresponding English catalog entry too.
+Generated browser labels use named templates while their underlying model names stay intact.
+
+Catalogs are parsed once and looked up through ordered maps. This is offline localization,
+not a claim of zero runtime overhead. The catalog tests check registered locale IDs,
+translation keys, and placeholder consistency. Run `cargo xtask ci` before submitting changes.
+
+## Rendering and coverage
+
+One immutable `Locale` type handles all translations. Table widgets without an app reference
+use a render scope that restores the previous locale when it exits, including nested renders.
+Standalone translated panels enter the same scope. Measure rendered text to size custom
+widgets; UTF-8 byte lengths do not describe their displayed width.
+
+The desktop host tries system CJK fonts and skips files that cannot be parsed. No system fonts
+are redistributed. Japanese glyph coverage depends on installed fonts; browser hosts cannot
+load local system fonts and must provide suitably licensed font assets separately.
+
+The current messages support named substitution, not locale-specific plural selection,
+number/date formatting, or right-to-left layout and shaping. Add those capabilities when
+introducing messages or languages that need them; use an established message formatter for
+plural rules instead of adding language branches to panels. The catalogs cover the UI surfaces
+introduced by this PR, not every engine error or every newer command dialog.