Localization (English + Canadian French)
ORIX Sheet ships in English (en, development language) and Canadian French (fr-CA). The app's
Info.plist declares both in CFBundleLocalizations; every Swift package bundle follows the language
the application chose.
How strings flow
| Layer | Catalog | Lookup |
|---|---|---|
| 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) |
| 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() |
| Feature packages | their own catalogs | their own L() |
Keys are the English text. A key that is missing from a catalog comes back unchanged (never empty,
never upper-cased): SheetUILocalization.string passes value: key.
Keys chosen at run time are either written as LK("…") (a marker that returns its argument and is
picked up by the extraction script: border presets, colour names, Help rows, paper sizes) or
enumerated from their source of truth by the script:
- number-format categories and preset names:
SheetFormat/BuiltinFormats.swift(catalog) andNumberFormatTools.basic; - function categories:
FunctionCategoryraw values inSheetCore/Engine/Registry.swift; - undo names of the engine:
transaction("…"),structural("…"),reshape(…, "…")inSheetCore/Engine/*.swift.
Undo names. session.perform("Paste") { … } and session.applyStyle("Bold") { … } take an
English key. WorkbookSession.registerUndo / applyUndo / applyRedo hand L(label) to
UndoManager.setActionName, so Edit ▸ Undo reads « Annuler Coller ». Labels given by the app target
(perform("Page Setup")) are looked up in the SheetUI catalog too, and the script files them there.
A feature that passes an already-localized label gets it back unchanged.
New sheets are named from L("Sheet") (« Feuille2 »); the first sheet of a new document from the
app key Sheet1 (« Feuille1 »).
API for feature packages
SheetUI components call L on their arguments. Because of the fallback, already-localized text
passes through, but the explicit variants avoid an accidental hit on a SheetUI key:
SectionHeader(localized: title)
InspectorSection(localized: title) { … }
EmptyStateView(systemImage:, localizedTitle:, localizedMessage:, localizedActionTitle:, action:)
MetricChip(localized: label, value)
ToolButton("plus", localizedHelp: tooltip, isOn: nil) { … } // isOn: nil = plain action button
WorkspaceAction.Group.localizedTitle // Insertion, Données, Analyse, Outils
WorkspacePane(id:, localizedTitle:, …) // existingWorkspaceAction.title is shown as given (features localize it themselves).
The script
Scripts/localize.py # scan the code, merge the tables, regenerate both catalogs
Scripts/localize.py --check # verify only; exit 1 on any problem
Scripts/localize.py --list # keys found in code, with the first place each is used
Scripts/localize.py --stubs # add missing keys to the tables with an empty valueTranslations are hand-maintained in Scripts/translations/sheetui.fr-CA.json and
Scripts/translations/app.fr-CA.json ({"English key": "traduction"}). The catalogs are generated
files: edit the tables, not the .xcstrings.
--check fails and lists:
- keys found in code without a translation (with the file and line of first use);
- translations whose format specifiers differ from the key (count, type, or a wrong
%1$@position); - a catalog that is not what the script would generate (someone edited code or tables without regenerating);
- a key that contains string interpolation.
It warns (without failing) about translations that no longer match a key and about French typography slips (straight apostrophe or quotes, colon without a space).
Format arguments: keep %@/%d in the same order, or number them (%1$@ : %2$@) to reorder.
French typography is applied when the catalog is written, so tables use ordinary spaces: no-break space before « : », inside « guillemets » and before « % », and « … » for three dots. Semicolons, question and exclamation marks take no space (Québec usage).
Adding a language
- Copy both tables to
Scripts/translations/sheetui.<lang>.jsonandapp.<lang>.jsonand translate the values. - Run
Scripts/localize.py; each catalog gains the language. - Add the language to
CFBundleLocalizationsinApp/Resources/Info.plist(throughproject.yml). - Feature packages have their own catalogs and need the same language, otherwise they stay in English.
- Run the app with
-AppleLanguages "(<lang>)"and the screenshot arguments below.
What stays in English, and why
- Product names: ORIX Sheet, Python Studio, ORIX Transform, ORIX Intelligence.
- Function names and signatures (
SUM,IF(test, value_if_true, …)): formulas are stored and typed in one locale-independent form; only argument and decimal separators follow Settings ▸ Formulas. - Number-format codes, cell references, file extensions, font names.
- Not translated yet because the text comes from packages outside SheetUI and the app target:
function summaries in the function browser (function libraries; only the eight special forms
defined in SheetUI are translated), formula parse errors (
ParseError.message, SheetCore), compatibility-issue texts (SheetIO), the#Sheet!A1syntax hint is translated but sheet names in existing workbooks are of course kept.
Verifying at run time
APP="build/DerivedData-l10n/Build/Products/Debug/ORIX Sheet.app/Contents/MacOS/ORIX Sheet"
"$APP" -AppleLanguages "(fr-CA)" -AppleLocale fr_CA -ORIXOpen file.xlsx -ORIXPane format \
-ORIXShot /tmp/orix-l10n-shots/fr-main.png -ORIXShotDelay 2.5 -ApplePersistenceIgnoreState YES
"$APP" -AppleLanguages "(fr-CA)" -ORIXDumpMenus /tmp/menus-fr.json # menu tree as JSON, then quitExtra arguments added for this: -ORIXFind 1 (open the find bar), -ORIXShotWindow settings|help|pagesetup (capture that window), -ORIXDumpMenus <path> (titles, key equivalents,
actions, alternates of the whole menu bar).
State on 2026-11-21, after the template chooser and the automation feature were added
(Scripts/localize.py --check): SheetUI 346 keys, all translated; app 218 keys, of which 8 have no
fr-CA translation (seven strings of App/Sources/TemplateChooser.swift and the Privacy text of
App/Sources/AppSettings.swift), and App/Resources/Localizable.xcstrings is reported out of date;
the check exits 1 with 9 problems. The previous Privacy sentence is still in the fr-CA table as an
unused translation.
An earlier menu dump taken the same day, before those two additions, had 200 items and 59
key equivalents in each language and every title of the app target
translated; it was not taken again. That no key equivalent is used twice is asserted on the current
menu bar by the app-hosted test testMenuBarHasNoDuplicateShortcuts. Items that AppKit inserts itself (Close All, Revert To, Share, Writing Tools, AutoFill,
Dictation, Emoji & Symbols, the globe-key alternate of Full Screen) are localized by the system.