Repository Public
1# Localization (English + Canadian French)23ORIX Sheet ships in English (`en`, development language) and Canadian French (`fr-CA`). The app's4`Info.plist` declares both in `CFBundleLocalizations`; every Swift package bundle follows the language5the application chose.67## How strings flow89| Layer | Catalog | Lookup |10|---|---|---|11| SheetUI (grid, toolbar, inspector, tabs, status bar) | `Packages/SheetUI/Sources/SheetUI/Resources/Localizable.xcstrings` | `L("English key")`, `L("Key %d", n)` in `Design/Localization.swift` (bundle `.module`) |12| App target (menu bar, Settings, Page Setup, Help, compatibility report, alerts) | `App/Resources/Localizable.xcstrings` | `NSLocalizedString("English key", comment: "")`; `MainMenu` builds titles through a local `L()` |13| Feature packages | their own catalogs | their own `L()` |1415Keys are the English text. A key that is missing from a catalog comes back unchanged (never empty,16never upper-cased): `SheetUILocalization.string` passes `value: key`.1718Keys chosen at run time are either written as `LK("…")` (a marker that returns its argument and is19picked up by the extraction script: border presets, colour names, Help rows, paper sizes) or20enumerated from their source of truth by the script:2122- number-format categories and preset names: `SheetFormat/BuiltinFormats.swift` (`catalog`) and23 `NumberFormatTools.basic`;24- function categories: `FunctionCategory` raw values in `SheetCore/Engine/Registry.swift`;25- undo names of the engine: `transaction("…")`, `structural("…")`, `reshape(…, "…")` in26 `SheetCore/Engine/*.swift`.2728**Undo names.** `session.perform("Paste") { … }` and `session.applyStyle("Bold") { … }` take an29English key. `WorkbookSession.registerUndo` / `applyUndo` / `applyRedo` hand `L(label)` to30`UndoManager.setActionName`, so Edit ▸ Undo reads « Annuler Coller ». Labels given by the app target31(`perform("Page Setup")`) are looked up in the SheetUI catalog too, and the script files them there.32A feature that passes an already-localized label gets it back unchanged.3334**New sheets** are named from `L("Sheet")` (« Feuille2 »); the first sheet of a new document from the35app key `Sheet1` (« Feuille1 »).3637## API for feature packages3839SheetUI components call `L` on their arguments. Because of the fallback, already-localized text40passes through, but the explicit variants avoid an accidental hit on a SheetUI key:4142```swift43SectionHeader(localized: title)44InspectorSection(localized: title) { … }45EmptyStateView(systemImage:, localizedTitle:, localizedMessage:, localizedActionTitle:, action:)46MetricChip(localized: label, value)47ToolButton("plus", localizedHelp: tooltip, isOn: nil) { … } // isOn: nil = plain action button48WorkspaceAction.Group.localizedTitle // Insertion, Données, Analyse, Outils49WorkspacePane(id:, localizedTitle:, …) // existing50```5152`WorkspaceAction.title` is shown as given (features localize it themselves).5354## The script5556```57Scripts/localize.py # scan the code, merge the tables, regenerate both catalogs58Scripts/localize.py --check # verify only; exit 1 on any problem59Scripts/localize.py --list # keys found in code, with the first place each is used60Scripts/localize.py --stubs # add missing keys to the tables with an empty value61```6263Translations are hand-maintained in `Scripts/translations/sheetui.fr-CA.json` and64`Scripts/translations/app.fr-CA.json` (`{"English key": "traduction"}`). The catalogs are generated65files: edit the tables, not the `.xcstrings`.6667`--check` fails and lists:6869- keys found in code without a translation (with the file and line of first use);70- translations whose format specifiers differ from the key (count, type, or a wrong `%1$@` position);71- a catalog that is not what the script would generate (someone edited code or tables without regenerating);72- a key that contains string interpolation.7374It warns (without failing) about translations that no longer match a key and about French typography75slips (straight apostrophe or quotes, colon without a space).7677Format arguments: keep `%@`/`%d` in the same order, or number them (`%1$@ : %2$@`) to reorder.7879French typography is applied when the catalog is written, so tables use ordinary spaces: no-break80space before « : », inside « guillemets » and before « % », and « … » for three dots. Semicolons,81question and exclamation marks take no space (Québec usage).8283## Adding a language84851. Copy both tables to `Scripts/translations/sheetui.<lang>.json` and `app.<lang>.json` and translate the values.862. Run `Scripts/localize.py`; each catalog gains the language.873. Add the language to `CFBundleLocalizations` in `App/Resources/Info.plist` (through `project.yml`).884. Feature packages have their own catalogs and need the same language, otherwise they stay in English.895. Run the app with `-AppleLanguages "(<lang>)"` and the screenshot arguments below.9091## What stays in English, and why9293- Product names: ORIX Sheet, Python Studio, ORIX Transform, ORIX Intelligence.94- Function names and signatures (`SUM`, `IF(test, value_if_true, …)`): formulas are stored and typed95 in one locale-independent form; only argument and decimal separators follow Settings ▸ Formulas.96- Number-format codes, cell references, file extensions, font names.97- Not translated yet because the text comes from packages outside SheetUI and the app target:98 function summaries in the function browser (function libraries; only the eight special forms99 defined in SheetUI are translated), formula parse errors (`ParseError.message`, SheetCore),100 compatibility-issue texts (SheetIO), the `#Sheet!A1` syntax hint is translated but sheet names in101 existing workbooks are of course kept.102103## Verifying at run time104105```106APP="build/DerivedData-l10n/Build/Products/Debug/ORIX Sheet.app/Contents/MacOS/ORIX Sheet"107"$APP" -AppleLanguages "(fr-CA)" -AppleLocale fr_CA -ORIXOpen file.xlsx -ORIXPane format \108 -ORIXShot /tmp/orix-l10n-shots/fr-main.png -ORIXShotDelay 2.5 -ApplePersistenceIgnoreState YES109"$APP" -AppleLanguages "(fr-CA)" -ORIXDumpMenus /tmp/menus-fr.json # menu tree as JSON, then quit110```111112Extra arguments added for this: `-ORIXFind 1` (open the find bar), `-ORIXShotWindow113settings|help|pagesetup` (capture that window), `-ORIXDumpMenus <path>` (titles, key equivalents,114actions, alternates of the whole menu bar).115116State on 2026-11-21, after the template chooser and the automation feature were added117(`Scripts/localize.py --check`): SheetUI 346 keys, all translated; app 218 keys, of which **8 have no118fr-CA translation** (seven strings of `App/Sources/TemplateChooser.swift` and the Privacy text of119`App/Sources/AppSettings.swift`), and `App/Resources/Localizable.xcstrings` is reported out of date;120the check exits 1 with 9 problems. The previous Privacy sentence is still in the fr-CA table as an121unused translation.122123An earlier menu dump taken the same day, before those two additions, had 200 items and 59124key equivalents in each language and every title of the app target125translated; it was not taken again. That no key equivalent is used twice is asserted on the current126menu bar by the app-hosted test `testMenuBarHasNoDuplicateShortcuts`. Items that AppKit inserts itself (Close All, Revert To, Share, Writing Tools, AutoFill,127Dictation, Emoji & Symbols, the globe-key alternate of Full Screen) are localized by the system.128