SPB Git

Repository Public

localization.md 7.3 KB

# 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) and NumberFormatTools.basic;
  • function categories: FunctionCategory raw values in SheetCore/Engine/Registry.swift;
  • undo names of the engine: transaction("…"), structural("…"), reshape(…, "…") in SheetCore/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:

swift
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:, …)                         // existing

WorkspaceAction.title is shown as given (features localize it themselves).

# The script

text
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 value

Translations 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

  1. Copy both tables to Scripts/translations/sheetui.<lang>.json and app.<lang>.json and translate the values.
  2. Run Scripts/localize.py; each catalog gains the language.
  3. Add the language to CFBundleLocalizations in App/Resources/Info.plist (through project.yml).
  4. Feature packages have their own catalogs and need the same language, otherwise they stay in English.
  5. 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!A1 syntax hint is translated but sheet names in existing workbooks are of course kept.

# Verifying at run time

text
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 quit

Extra 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.

Files main
Menu

Theme