Repository Public
1#!/usr/bin/env python32"""ORIX Sheet — string catalogs of the shared UI layer (SheetUI) and of the app target.34 Scripts/localize.py regenerate both Localizable.xcstrings from code + translation tables5 Scripts/localize.py --check verify only; exit 1 on any problem (CI / pre-commit)6 Scripts/localize.py --list print the keys found in code, per catalog7 Scripts/localize.py --stubs add missing keys to the translation tables with an empty value89How it works10 1. The Swift sources are scanned for every call that takes an English catalog key (the patterns are11 listed in SHEETUI_PATTERNS / APP_PATTERNS below). Keys chosen at run time are either wrapped in the12 `LK("…")` marker in code or enumerated from their source of truth (number-format presets, function13 categories, undo labels of the engine).14 2. Translations are hand-maintained in Scripts/translations/<catalog>.<language>.json15 ({"English key": "translation"}). One file per language: adding `sheetui.de.json` + `app.de.json`16 adds German to both catalogs.17 3. The catalogs are regenerated: sourceLanguage en, every key with a `translated` stringUnit per language.1819French typography is applied by the script (translators type ordinary spaces): no-break space before20« : », inside « guillemets » and before « % », and « … » instead of three dots.21"""22from __future__ import annotations2324import json25import re26import sys27from pathlib import Path2829ROOT = Path(__file__).resolve().parent.parent30TRANSLATIONS = ROOT / "Scripts" / "translations"3132SHEETUI_SOURCES = ROOT / "Packages" / "SheetUI" / "Sources" / "SheetUI"33APP_SOURCES = ROOT / "App" / "Sources"34SHEETCORE_ENGINE = ROOT / "Packages" / "SheetCore" / "Sources" / "SheetCore" / "Engine"35BUILTIN_FORMATS = ROOT / "Packages" / "SheetFormat" / "Sources" / "SheetFormat" / "BuiltinFormats.swift"3637CATALOGS = {38 "sheetui": SHEETUI_SOURCES / "Resources" / "Localizable.xcstrings",39 "app": ROOT / "App" / "Resources" / "Localizable.xcstrings",40}4142# A pattern matches the text that comes immediately BEFORE the opening quote of a key literal.43SHEETUI_PATTERNS = [44 r"\bL\(\s*", # L("key") / L("key %d", n)45 r"\bLK\(\s*", # LK("key") marker for keys chosen at run time46 r"\bText\(l:\s*", # Text(l: "key")47 r"\bhelp:\s*", # ToolButton(_, help: "key"), ColorMenu(help:)48 r"\b(?:SectionHeader|InspectorSection|MetricChip)\(\s*",49 r"\b(?:title|message|actionTitle):\s*", # EmptyStateView(title:message:actionTitle:)50 r"\bperform\(\s*", # session.perform("Undo name") { … }51 r"\bapplyStyle\(\s*", # session.applyStyle("Undo name") { … }52 r"\bupdateObject\([^\n\"]*\blabel:\s*", # updateObject(_, label: "Undo name")53 r"\bitem\(\s*", # GridView context menu: item("Title", #selector…)54]55APP_PATTERNS = [56 r"\bNSLocalizedString\(\s*",57 r"\bLK\(\s*",58]59APP_MENU_PATTERNS = [ # MainMenu.swift builds titles through a local L()60 r"\bL\(\s*",61 r"\b(?:item|menu|sub)\(\s*",62]63# Undo names given in the app target are looked up in the SheetUI catalog (WorkbookSession.registerUndo).64APP_TO_SHEETUI_PATTERNS = [r"\.perform\(\s*", r"\bapplyStyle\(\s*"]6566SPECIFIER = re.compile(r"%(?:(\d+)\$)?[-+0 #]*\d*(?:\.\d+)?(?:hh|h|ll|l|q|z|t|j)?([@dDiuUxXoOfFeEgGaAcCsSp])|%%")676869class ScanError(Exception):70 pass717273def swift_literal(src: str, pos: int, where: str) -> tuple[str, int] | None:74 """Parses the Swift string literal whose opening quote is at src[pos]; returns (value, end) or None."""75 if pos >= len(src) or src[pos] != '"' or src.startswith('"""', pos):76 return None77 out, i = [], pos + 178 while i < len(src):79 c = src[i]80 if c == '"':81 return "".join(out), i + 182 if c == "\n":83 return None84 if c == "\\":85 n = src[i + 1]86 if n == "(":87 raise ScanError(f"{where}: a catalog key cannot contain string interpolation: {src[pos:pos + 60]!r}")88 if n == "u":89 m = re.match(r"\\u\{([0-9A-Fa-f]+)\}", src[i:])90 if not m:91 raise ScanError(f"{where}: bad unicode escape")92 out.append(chr(int(m.group(1), 16)))93 i += m.end()94 continue95 out.append({"n": "\n", "t": "\t", "r": "\r", "0": "\0", '"': '"', "'": "'", "\\": "\\"}.get(n, n))96 i += 297 continue98 out.append(c)99 i += 1100 return None101102103def strip_comments(src: str) -> str:104 """Blanks // comments (outside string literals) so that examples in documentation are not extracted."""105 out = []106 for line in src.split("\n"):107 i, in_string = 0, False108 while i < len(line):109 c = line[i]110 if c == "\\" and in_string:111 i += 2112 continue113 if c == '"':114 in_string = not in_string115 elif c == "/" and not in_string and line.startswith("//", i):116 line = line[:i]117 break118 i += 1119 out.append(line)120 return "\n".join(out)121122123def scan(files: list[Path], patterns: list[str]) -> dict[str, list[str]]:124 """key → places where it is used."""125 found: dict[str, list[str]] = {}126 rx = re.compile("(?:" + "|".join(patterns) + ')(?=")')127 for path in files:128 src = strip_comments(path.read_text(encoding="utf-8"))129 for m in rx.finditer(src):130 line = src.count("\n", 0, m.end()) + 1131 where = f"{path.relative_to(ROOT)}:{line}"132 lit = swift_literal(src, m.end(), where)133 if lit is None or lit[0] == "":134 continue135 found.setdefault(lit[0], []).append(where)136 return found137138139def enumerated_sheetui_keys() -> dict[str, list[str]]:140 """Keys whose values live outside SheetUI but are shown through SheetUI's catalog."""141 found: dict[str, list[str]] = {}142143 def add(key: str, where: str) -> None:144 if key:145 found.setdefault(key, []).append(where)146147 # undo/redo names of the calculation engine (Edit ▸ Undo …)148 for path in sorted(SHEETCORE_ENGINE.glob("*.swift")):149 src = strip_comments(path.read_text(encoding="utf-8"))150 rel = str(path.relative_to(ROOT))151 for m in re.finditer(r'\b(?:transaction|structural)\(\s*(?=")', src):152 lit = swift_literal(src, m.end(), rel)153 if lit:154 add(lit[0], f"{rel} (undo name)")155 for m in re.finditer(r'\breshape\([^\n]*?,\s*(?="[^"\n]*"\)\s*\})', src):156 lit = swift_literal(src, m.end(), rel)157 if lit:158 add(lit[0], f"{rel} (undo name)")159 # function categories: enum FunctionCategory … case math = "Math", …160 m = re.search(r"enum FunctionCategory\b[^{]*\{(.*?)\n\}", src, re.S)161 if m:162 for raw in re.findall(r'=\s*"([^"]+)"', m.group(1)):163 add(raw, f"{rel} (FunctionCategory)")164 # number-format presets: (category, name, code) tuples165 tuple_rx = re.compile(r'\(\s*"((?:[^"\\]|\\.)*)"\s*,\s*"((?:[^"\\]|\\.)*)"\s*,\s*"')166 for path, start in [(BUILTIN_FORMATS, "public static let catalog"), (SHEETUI_SOURCES / "Session" / "Providers.swift", "public static let basic")]:167 src = path.read_text(encoding="utf-8")168 rel = str(path.relative_to(ROOT))169 i = src.find(start)170 if i < 0:171 raise ScanError(f"{rel}: '{start}' not found (number-format presets moved?)")172 for cat, name in tuple_rx.findall(src[i:]):173 add(cat, f"{rel} (format category)")174 add(name, f"{rel} (format preset)")175 return found176177178def collect() -> dict[str, dict[str, list[str]]]:179 sheetui_files = sorted(SHEETUI_SOURCES.rglob("*.swift"))180 app_files = sorted(APP_SOURCES.glob("*.swift"))181 sheetui = scan(sheetui_files, SHEETUI_PATTERNS)182 for k, v in enumerated_sheetui_keys().items():183 sheetui.setdefault(k, []).extend(v)184 for k, v in scan(app_files, APP_TO_SHEETUI_PATTERNS).items():185 sheetui.setdefault(k, []).extend(v)186 app = scan(app_files, APP_PATTERNS)187 for k, v in scan([APP_SOURCES / "MainMenu.swift"], APP_MENU_PATTERNS).items():188 app.setdefault(k, []).extend(v)189 return {"sheetui": sheetui, "app": app}190191192def specifiers(s: str) -> list[tuple[int | None, str]]:193 out = []194 for m in SPECIFIER.finditer(s):195 if m.group(0) == "%%":196 continue197 out.append((int(m.group(1)) if m.group(1) else None, m.group(2).lower().replace("i", "d")))198 return out199200201def specifier_problem(key: str, value: str) -> str | None:202 """None when `value` consumes exactly the arguments of `key`, in a position-safe way."""203 src, dst = specifiers(key), specifiers(value)204 src_types = [t for _, t in src]205 if any(p is not None for p, _ in src):206 return "the key itself must not use positional specifiers"207 if not dst and not src:208 if value.count("%") - 2 * value.count("%%") != key.count("%") - 2 * key.count("%%"):209 return "stray % sign"210 return None211 positional = [p for p, _ in dst if p is not None]212 if positional and len(positional) != len(dst):213 return "mixes positional (%1$@) and sequential (%@) specifiers"214 if positional:215 by_pos: dict[int, str] = {}216 for p, t in dst:217 if by_pos.setdefault(p, t) != t:218 return f"argument {p} is used with two different types"219 if sorted(by_pos) != list(range(1, len(src) + 1)):220 return f"uses arguments {sorted(by_pos)} but the key has {len(src)}"221 if [by_pos[i] for i in range(1, len(src) + 1)] != src_types:222 return f"argument types {[by_pos[i] for i in sorted(by_pos)]} differ from the key's {src_types}"223 return None224 if [t for _, t in dst] != src_types:225 return f"specifiers {[t for _, t in dst]} differ from the key's {src_types} (use %1$@, %2$d… to reorder)"226 return None227228229NBSP = "\u00a0"230231232def typography(lang: str, s: str) -> str:233 if not lang.lower().startswith("fr"):234 return s235 s = s.replace("...", "…")236 s = re.sub(r"[ \u202f]:(?=\s|$)", NBSP + ":", s) # « : »237 s = re.sub(r"«[ \u202f]", "«" + NBSP, s)238 s = re.sub(r"[ \u202f]»", NBSP + "»", s)239 s = re.sub(r"(?<=[\dd@}])[ \u202f]%", NBSP + "%", s) # 100 %, %d %%240 return s241242243def typography_problems(lang: str, s: str) -> list[str]:244 if not lang.lower().startswith("fr"):245 return []246 out = []247 if re.search(r"\S:(?=\s|$)", s) and not re.search(r"https?:|mailto:|\d:\d|&[A-Z]:", s):248 out.append("colon without a (no-break) space before it")249 if "'" in s:250 out.append("straight apostrophe (use ’)")251 if re.search(r'"[^"]+"', s):252 out.append("straight double quotes (use « »)")253 return out254255256def load_tables(catalog: str) -> dict[str, dict[str, str]]:257 """language → {key: translation}"""258 tables = {}259 for path in sorted(TRANSLATIONS.glob(f"{catalog}.*.json")):260 lang = path.name[len(catalog) + 1:-len(".json")]261 data = json.loads(path.read_text(encoding="utf-8"))262 tables[lang] = {k: v for k, v in data.items() if not k.startswith("_")}263 return tables264265266def render(keys: list[str], tables: dict[str, dict[str, str]]) -> str:267 strings = {}268 for key in keys:269 locs = {}270 for lang, table in sorted(tables.items()):271 if table.get(key):272 locs[lang] = {"stringUnit": {"state": "translated", "value": typography(lang, table[key])}}273 strings[key] = {"localizations": locs} if locs else {}274 doc = {"sourceLanguage": "en", "strings": strings, "version": "1.0"}275 return json.dumps(doc, ensure_ascii=False, indent=2, sort_keys=True, separators=(",", " : ")) + "\n"276277278def main(argv: list[str]) -> int:279 check, listing, stubs = "--check" in argv, "--list" in argv, "--stubs" in argv280 try:281 found = collect()282 except ScanError as e:283 print(f"error: {e}", file=sys.stderr)284 return 1285 problems: list[str] = []286 warnings: list[str] = []287 for catalog, path in CATALOGS.items():288 keys = sorted(found[catalog])289 if listing:290 print(f"# {catalog}: {len(keys)} keys")291 for k in keys:292 print(json.dumps(k, ensure_ascii=False), " <- ", found[catalog][k][0])293 continue294 tables = load_tables(catalog)295 if not tables:296 problems.append(f"{catalog}: no translation table Scripts/translations/{catalog}.<language>.json")297 for lang, table in tables.items():298 table_path = TRANSLATIONS / f"{catalog}.{lang}.json"299 missing = [k for k in keys if not table.get(k)]300 if stubs and missing:301 raw = json.loads(table_path.read_text(encoding="utf-8"))302 for k in missing:303 raw.setdefault(k, "")304 table_path.write_text(json.dumps(raw, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")305 print(f"{table_path.relative_to(ROOT)}: added {len(missing)} empty entries to translate")306 for k in missing:307 problems.append(f"{catalog} [{lang}] missing translation: {json.dumps(k, ensure_ascii=False)} (used at {found[catalog][k][0]})")308 for k in keys:309 v = table.get(k)310 if not v:311 continue312 p = specifier_problem(k, v)313 if p:314 problems.append(f"{catalog} [{lang}] format specifiers of {json.dumps(k, ensure_ascii=False)} → {json.dumps(v, ensure_ascii=False)}: {p}")315 if v != v.strip() and k == k.strip():316 problems.append(f"{catalog} [{lang}] leading/trailing space in the translation of {json.dumps(k, ensure_ascii=False)}")317 for t in typography_problems(lang, typography(lang, v)):318 warnings.append(f"{catalog} [{lang}] typography of {json.dumps(v, ensure_ascii=False)}: {t}")319 for k in sorted(set(table) - set(keys)):320 warnings.append(f"{catalog} [{lang}] unused translation (no such key in code): {json.dumps(k, ensure_ascii=False)}")321 text = render(keys, tables)322 if check:323 current = path.read_text(encoding="utf-8") if path.exists() else None324 if current != text:325 problems.append(f"{path.relative_to(ROOT)} is out of date: run Scripts/localize.py")326 else:327 doc = json.loads(current)328 for lang in tables:329 untranslated = [k for k, v in doc["strings"].items() if v.get("localizations", {}).get(lang, {}).get("stringUnit", {}).get("state") != "translated"]330 if untranslated:331 problems.append(f"{path.relative_to(ROOT)}: {len(untranslated)} keys without a translated {lang} unit")332 else:333 path.parent.mkdir(parents=True, exist_ok=True)334 path.write_text(text, encoding="utf-8")335 print(f"{catalog}: {len(keys)} keys, languages: {', '.join(sorted(tables)) or '—'} → {path.relative_to(ROOT)}" + (" (checked)" if check else " (written)"))336 for w in warnings:337 print("warning:", w)338 for p in problems:339 print("error:", p, file=sys.stderr)340 if problems:341 print(f"{len(problems)} problem(s)", file=sys.stderr)342 return 1343 return 0344345346if __name__ == "__main__":347 sys.exit(main(sys.argv[1:]))348