import Foundation // Catalog structure is kept intact; only translated string units are developer text. enum LocalizationTools { static let pseudoLanguage = "en-XA" static func run(_ command: String, _ args: [String]) throws { switch command { case "prepare-pseudo-catalog": guard args.count == 2 else { throw DevError("Usage: prepare-pseudo-catalog SOURCE DESTINATION") } try pseudoCatalog(DevJSON.read(args[0])).encoded().write(to: URL(fileURLWithPath: args[1])) case "check-localization": guard args.count == 1 else { throw DevError("Usage: check-localization REPOSITORY") } let failures = try audit(URL(fileURLWithPath: args[0])) guard failures.isEmpty else { throw DevError(failures.joined(separator: "\n")) } print("Localization catalogs, placeholders, and source checks passed") default: throw DevError("Unknown localization command: \(command)") } } static func pseudoCatalog(_ input: DevJSON) throws -> DevJSON { var catalog = try CheckTools.preparedCatalog(input).requireObject() guard catalog["sourceLanguage"] == .string("en") else { throw DevError("Pseudo-localization requires an English source catalog") } var entries = try (catalog["strings"] ?? .null).requireObject() for (key, value) in entries { var entry = try value.requireObject() var localizations = try (entry["localizations"] ?? .null).requireObject() guard let english = localizations["en"] else { throw DevError("Missing source translation: \(key)") } localizations[pseudoLanguage] = try pseudoUnits(english) entry["localizations"] = .object(localizations) entries[key] = .object(entry) } catalog["strings"] = .object(entries) return .object(catalog) } private static func pseudoUnits(_ node: DevJSON) throws -> DevJSON { switch node { case .object(var object): if let unit = object["stringUnit"] { var unit = try unit.requireObject() guard let value = unit["value"]?.string else { throw DevError("String unit needs a value") } unit["value"] = .string(try pseudoText(value)) unit["state"] = .string("translated") object["stringUnit"] = .object(unit) } for (key, value) in object where key != "stringUnit" { object[key] = try pseudoUnits(value) } return .object(object) case .array(let values): return .array(try values.map(pseudoUnits)) default: return node } } static func formatTokens(_ text: String) throws -> [NSRange] { // Includes printf positions, dynamic width/precision, lengths, literal percent and catalog substitutions. let regex = try NSRegularExpression( pattern: #"%%|%(?:\d+\$)?#@[^@]+@|%(?:\d+\$)?[-+ #0']*(?:\d+|\*(?:\d+\$)?)?(?:\.(?:\d+|\*(?:\d+\$)?))?(?:hh|ll|[hljztLq])?[@diuoxXfFeEgGaAcCsSpnDUO]"# ) return regex.matches(in: text, range: NSRange(text.startIndex..., in: text)).map(\.range) } static func pseudoText(_ text: String) throws -> String { guard !text.isEmpty else { return text } let alphabet = Array("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") let accented = Array("áƀçďéƒğĥíĵķľḿñóƥɋŕšţúṽŵẋýžÁɃÇĎÉƑĞĤÍĴĶĽḾÑÓƤɊŔŠŢÚṼŴẊÝŽ") let accents = Dictionary(uniqueKeysWithValues: zip(alphabet, accented)) var result = "" var cursor = text.startIndex var literalCount = 0 func appendLiteral(_ literal: Substring) { literalCount += literal.count for character in literal { result.append(accents[character] ?? character) } } for token in try formatTokens(text) { guard let range = Range(token, in: text) else { throw DevError("Invalid format-token range") } appendLiteral(text[cursor.., path: String) throws -> [String] { let fragment = try NSRegularExpression( pattern: #"\|\||&&|\.[A-Za-z_]\w*\s*\(|\b(?:let|var)\s+[A-Za-z_]\w*\s*(?:=|:)|\bfunc\s+[A-Za-z_]\w*\s*\(|\b(?:if|guard|for|while|switch)\b[^\n]*[{}]|\b(?:return|throw|try|await)\s+[A-Za-z_]\w*\s*(?:\(|\.[A-Za-z_]\w*)"# ) return keys.compactMap { key in guard fragment.firstMatch(in: key, range: NSRange(key.startIndex..., in: key)) != nil else { return nil } return "\(path): catalog key looks like a code fragment: \(key)" } } static func audit(_ root: URL) throws -> [String] { var failures: [String] = [] var modules: [String: [String: Set]] = [:] var catalogs: [(path: String, entries: [String: DevJSON])] = [] var localizedLanguages = Set() let sources = root.appendingPathComponent("Sources") for module in try FileManager.default.contentsOfDirectory(at: sources, includingPropertiesForKeys: nil) { let resources = module.appendingPathComponent("Resources") guard FileManager.default.fileExists(atPath: resources.path) else { continue } var tables: [String: Set] = [:] for file in try FileManager.default.contentsOfDirectory(at: resources, includingPropertiesForKeys: nil) where file.pathExtension == "xcstrings" { let catalog = try DevJSON.read(file.path) let entries = try (catalog["strings"] ?? .null).requireObject() failures += try catalogKeyFailures(entries.keys, path: file.path) tables[file.deletingPathExtension().lastPathComponent] = Set(entries.keys) catalogs.append((file.path, entries)) if catalog["sourceLanguage"] != .string("en") { failures.append("\(file.path): sourceLanguage must be en") } for (key, entry) in entries { if entry["extractionState"] == .string("stale") { failures.append("\(file.path): stale extraction state for \(key)") } if entry["localizations"]?[pseudoLanguage] != nil { failures.append("\(file.path): pseudo resources must be generated, not committed (\(key))") } if let localizations = entry["localizations"]?.object { localizedLanguages.formUnion(localizations.keys.filter { $0 != "en" && $0 != pseudoLanguage }) } let english = entry["localizations"]?["en"] ?? sourceUnit(key) failures += try unitFailures(english, context: "\(file.path): \(key)") } } modules[module.lastPathComponent] = tables } for (path, entries) in catalogs { for (key, entry) in entries { guard entry["shouldTranslate"] != .bool(false) else { continue } let english = entry["localizations"]?["en"] ?? sourceUnit(key) for language in localizedLanguages { guard let localized = entry["localizations"]?[language] else { failures.append("\(path): missing \(language) localization for \(key)") continue } failures += try localizationFailures( english, localized, context: "\(path): \(key) [\(language)]", language: language) } } } for module in ["ParcelUI", "ParcelApp"] { let directory = sources.appendingPathComponent(module) guard let files = FileManager.default.enumerator(at: directory, includingPropertiesForKeys: nil) else { throw DevError("Cannot enumerate \(directory.path)") } for case let file as URL in files where file.pathExtension == "swift" { let name = file.lastPathComponent guard module == "ParcelUI" || name.contains("Notice") || name.contains("Tour") || name.contains("Menu") || ["AppText.swift", "AppShortcutEnvironment.swift"].contains(name) else { continue } let source = try String(contentsOf: file, encoding: .utf8) failures += try sourceFailures(source, path: file.path, tables: modules[module] ?? [:]) } } return failures.sorted() } static func localizationFailures( _ english: DevJSON, _ localized: DevJSON, context: String, language: String? = nil ) throws -> [String] { var failures = stateFailures(localized, context: context) let sourceUnits = stringUnits(english) let localizedUnits = stringUnits(localized) for (path, value) in localizedUnits { guard let sourcePath = matchingSourcePath(for: path, in: sourceUnits, language: language), let sourceValue = sourceUnits[sourcePath] else { failures.append("\(context): unexpected localized string unit at \(path)") continue } let signature = try placeholderSignature(value) let sourceSignature = try placeholderSignature(sourceValue) if signature != sourceSignature { // Some languages select “one” at zero and must render the count instead of spelling out “one”. let other = sourceUnits.first { pluralFamily($0.key) == pluralFamily(sourcePath) && pluralCategory($0.key) == "other" } let otherSignature = try other.map { try placeholderSignature($0.value) } let numericOne = pluralCategory(sourcePath) == "one" && sourceSignature.isEmpty && signature.count == 1 && signature.first?.key.hasSuffix(":lld") == true && signature.first?.value == 1 && signature == otherSignature if !numericOne { failures.append("\(context): placeholder mismatch at \(path)") } } } for path in sourceUnits.keys where matchingLocalizedPath(for: path, in: localizedUnits, language: language) == nil { failures.append("\(context): missing localized string unit at \(path)") } if substitutionMetadata(english) != substitutionMetadata(localized) { failures.append("\(context): format substitution metadata mismatch") } return failures } // A catalog key is its source text when it has no explicit English localization. private static func sourceUnit(_ key: String) -> DevJSON { .object(["stringUnit": .object(["value": .string(key)])]) } private static func stateFailures(_ node: DevJSON, context: String, path: String = "") -> [String] { var failures: [String] = [] if let unit = node["stringUnit"] { if unit["value"]?.string == nil { failures.append("\(context): string unit needs a value at \(path)") } if unit["state"]?.string != "translated" { failures.append("\(context): localization state must be translated at \(path)") } } if let object = node.object { for (key, value) in object where key != "stringUnit" { failures += stateFailures(value, context: context, path: path.isEmpty ? key : "\(path)/\(key)") } } else if let array = node.array { for (index, value) in array.enumerated() { failures += stateFailures(value, context: context, path: "\(path)[\(index)]") } } return failures } private static func stringUnits(_ node: DevJSON, path: String = "") -> [String: String] { var result: [String: String] = [:] if let value = node["stringUnit"]?["value"]?.string { result[path.isEmpty ? "stringUnit" : "\(path)/stringUnit"] = value } if let object = node.object { for (key, value) in object where key != "stringUnit" { let childPath = path.isEmpty ? key : "\(path)/\(key)" result.merge(stringUnits(value, path: childPath)) { current, _ in current } } } else if let array = node.array { for (index, value) in array.enumerated() { result.merge(stringUnits(value, path: "\(path)[\(index)]")) { current, _ in current } } } return result } private static func substitutionMetadata(_ node: DevJSON, path: String = "") -> [String: DevJSON] { var result: [String: DevJSON] = [:] if node["argNum"] != nil || node["formatSpecifier"] != nil { result[path] = .object([ "argNum": node["argNum"] ?? .null, "formatSpecifier": node["formatSpecifier"] ?? .null, ]) } if let object = node.object { for (key, value) in object where key != "stringUnit" { let childPath = path.isEmpty ? key : "\(path)/\(key)" result.merge(substitutionMetadata(value, path: childPath)) { current, _ in current } } } else if let array = node.array { for (index, value) in array.enumerated() { result.merge(substitutionMetadata(value, path: "\(path)[\(index)]")) { current, _ in current } } } return result } private static func matchingSourcePath( for localizedPath: String, in source: [String: String], language: String? ) -> String? { if let category = pluralCategory(localizedPath), !pluralCategories(for: language).contains(category) { return nil } if source[localizedPath] != nil { return localizedPath } guard let family = pluralFamily(localizedPath) else { return nil } return source.keys.sorted().first { pluralFamily($0) == family && pluralCategory($0) == "other" } ?? source.keys.sorted().first { pluralFamily($0) == family } } private static func matchingLocalizedPath( for sourcePath: String, in localized: [String: String], language: String? ) -> String? { let expectedCategories = pluralCategories(for: language) guard let category = pluralCategory(sourcePath) else { return localized[sourcePath] == nil ? nil : sourcePath } if expectedCategories.contains(category), localized[sourcePath] != nil { return sourcePath } guard category == "one", !expectedCategories.contains("one"), let family = pluralFamily(sourcePath) else { return nil } return localized.keys.first { pluralFamily($0) == family && pluralCategory($0) == "other" } } private static func pluralCategories(for language: String?) -> Set { switch language { case "ja", "zh-Hans", "ko": ["other"] default: ["one", "other"] } } private static func pluralCategory(_ path: String) -> String? { let components = path.split(separator: "/") guard let pluralIndex = components.lastIndex(of: "plural"), components.indices.contains(pluralIndex + 1) else { return nil } return String(components[pluralIndex + 1]) } private static func pluralFamily(_ path: String) -> String? { let components = path.split(separator: "/") guard let pluralIndex = components.lastIndex(of: "plural"), components.indices.contains(pluralIndex + 1) else { return nil } return components.enumerated().filter { $0.offset != pluralIndex + 1 }.map { String($0.element) } .joined(separator: "/") } private static func placeholderSignature(_ text: String) throws -> [String: Int] { var signature: [String: Int] = [:] var nextArgument = 1 func addArgument(_ index: Int?, type: String) { let argument = index ?? nextArgument signature["arg\(argument):\(type)", default: 0] += 1 nextArgument = max(nextArgument, argument + 1) } let stars = try NSRegularExpression(pattern: #"\*(\d+)\$?"#) let conversion = try NSRegularExpression( pattern: #"%(\d+\$)?[-+ #0']*(?:\d+|\*(?:\d+\$)?)?(?:\.(?:\d+|\*(?:\d+\$)?))?(hh|ll|[hljztLq])?([@diuoxXfFeEgGaAcCsSpnDUO])"# ) let substitution = try NSRegularExpression(pattern: #"#@([^@]+)@"#) let argumentPosition = try NSRegularExpression(pattern: #"^%(\d+)\$"#) for range in try formatTokens(text) { guard let range = Range(range, in: text) else { throw DevError("Invalid format-token range") } let token = String(text[range]) if token.hasPrefix("% "), range.lowerBound > text.startIndex, text[text.index(before: range.lowerBound)].isNumber { // A localized percentage like “10% a 90%” is literal, not a printf conversion. continue } if token == "%%" { signature["literal%%", default: 0] += 1 continue } if let match = substitution.firstMatch(in: token, range: NSRange(token.startIndex..., in: token)) { guard let name = capture(match, group: 1, in: token) else { throw DevError("Invalid catalog substitution token: \(token)") } let position = argumentPosition.firstMatch(in: token, range: NSRange(token.startIndex..., in: token)) addArgument(position.flatMap { capture($0, group: 1, in: token).flatMap(Int.init) }, type: "#@\(name)@") continue } for match in stars.matches(in: token, range: NSRange(token.startIndex..., in: token)) { addArgument(capture(match, group: 1, in: token).flatMap(Int.init), type: "int") } guard let match = conversion.firstMatch(in: token, range: NSRange(token.startIndex..., in: token)), let specifier = capture(match, group: 3, in: token) else { throw DevError("Unrecognized format token: \(token)") } let length = capture(match, group: 2, in: token) ?? "" let position = argumentPosition.firstMatch(in: token, range: NSRange(token.startIndex..., in: token)) addArgument( position.flatMap { capture($0, group: 1, in: token).flatMap(Int.init) }, type: length + specifier) } let inflections = try NSRegularExpression( pattern: #"\^\[.*?\]\(inflect: true\)"#, options: [.dotMatchesLineSeparators]) let inflectionCount = inflections.numberOfMatches(in: text, range: NSRange(text.startIndex..., in: text)) if inflectionCount > 0 { signature["inflect: true"] = inflectionCount } let keycaps: [Character] = ["⌃", "⌥", "⇧", "⌘"] for keycap in keycaps { let count = text.filter { $0 == keycap }.count if count > 0 { signature["keycap:\(keycap)"] = count } } return signature } private static func capture(_ match: NSTextCheckingResult, group: Int, in text: String) -> String? { let range = match.range(at: group) guard range.location != NSNotFound, let range = Range(range, in: text) else { return nil } return String(text[range]) } private static func unitFailures(_ node: DevJSON, context: String) throws -> [String] { var failures: [String] = [] if let unit = node["stringUnit"] { if unit["value"]?.string == nil { failures.append("\(context): stringUnit needs a string value") } } if let object = node.object { for (key, value) in object where key != "stringUnit" { failures += try unitFailures(value, context: context) } } else if let array = node.array { for value in array { failures += try unitFailures(value, context: context) } } return failures } static func sourceFailures(_ source: String, path: String, tables: [String: Set]) throws -> [String] { var failures: [String] = [] let helpers = [ "UIStrings.text": "UI", "SettingsText.string": "Settings", "MenuText.text": "Menu", "TourText.text": "TourSetup", "TourDemoText.text": "TourDemos", "TourDemoText.format": "TourDemos", "AppText.string": "App", "AppText.localized": "App", "AppText.notice": "Notices", "minimumsText": "Minimums", "SupportText.text": "Support", "WhatsNewText.text": "WhatsNew", "AppearanceText.string": "Appearance", "LanguageText.string": "Language", "LanguageText.format": "Language", ] let sinks = [ "Text", "Button", "Label", "Toggle", "Picker", "Section", "TextField", "LabeledContent", "accessibilityLabel", "accessibilityHint", "help", "navigationTitle", "confirmationDialog", "alert", "setAccessibilityLabel", "NSMenu", "NSMenuItem", "LearningPanel", ] let functions = Array(helpers.keys) + sinks + ["String", "NSLocalizedString", "Bundle.main.localizedString"] for function in functions { for call in try calls(source, function: function) { let line = source[..) -> Bool { if keys.contains(key) { return true } // Swift interpolation overloads infer numeric types; this audit doesn't pretend to type-check Swift. let normalized = key.replacingOccurrences(of: "%@", with: "%lld") if keys.contains(normalized) { return true } return keys.contains { $0.replacingOccurrences(of: "%lld", with: "%@").replacingOccurrences(of: "%g", with: "%@") == key } } private struct Call { let start: String.Index; let arguments: String } private static func calls(_ source: String, function: String) throws -> [Call] { let regex = try NSRegularExpression( pattern: #"\b"# + NSRegularExpression.escapedPattern(for: function) + #"\s*\("#) var calls: [Call] = [] for match in regex.matches(in: source, range: NSRange(source.startIndex..., in: source)) { guard let range = Range(match.range, in: source) else { throw DevError("Invalid source range") } let start = range.upperBound if let end = try closingParenthesis(source, start: start) { calls.append( Call( start: range.lowerBound, arguments: String(source[start.. String.Index? { var depth = 1 var cursor = start while cursor < text.endIndex { let character = text[cursor] if character == "\"" { cursor = try afterQuotedString(text, start: text.index(after: cursor)) continue } if character == "(" { depth += 1 } if character == ")" { depth -= 1 } if depth == 0 { return cursor } cursor = text.index(after: cursor) } return nil } private static func afterQuotedString(_ text: String, start: String.Index) throws -> String.Index { var cursor = start while cursor < text.endIndex { let next = text.index(after: cursor) if text[cursor] == "\"" { return next } if text[cursor] == "\\", next < text.endIndex { if text[next] == "(" { guard let end = try closingParenthesis(text, start: text.index(after: next)) else { throw DevError("Unclosed string interpolation") } cursor = text.index(after: end) } else { cursor = text.index(after: next) } } else { cursor = next } } throw DevError("Unclosed source string") } private static func firstArgument(_ text: String) throws -> String { var depth = 0 var index = text.startIndex while index < text.endIndex { let character = text[index] if character == "\"" { index = try afterQuotedString(text, start: text.index(after: index)) continue } if "([{".contains(character) { depth += 1 } if ")]}".contains(character) { depth -= 1 } if character == ",", depth == 0 { return String(text[.. String? { let regex = try NSRegularExpression(pattern: #"\b"# + label + #":\s*\"([^\"]+)\""#) guard let match = regex.firstMatch(in: arguments, range: NSRange(arguments.startIndex..., in: arguments)), let range = Range(match.range(at: 1), in: arguments) else { return nil } return String(arguments[range]) } static func literalKeys(_ text: String) throws -> [String] { var normalized = "" var cursor = text.startIndex while cursor < text.endIndex { let next = text.index(after: cursor) if text[cursor] == "\\", next < text.endIndex { if text[next] == "(" { let start = text.index(after: next) guard let end = try closingParenthesis(text, start: start) else { throw DevError("Unclosed string interpolation") } normalized += "%@" cursor = text.index(after: end) continue } normalized.append(text[cursor]); normalized.append(text[next]) cursor = text.index(after: next) continue } normalized.append(text[cursor]); cursor = next } let regex = try NSRegularExpression(pattern: #"\"(?:\\.|[^\"\\])*\""#) return try regex.matches(in: normalized, range: NSRange(normalized.startIndex..., in: normalized)).map { match in guard let range = Range(match.range, in: normalized) else { throw DevError("Invalid literal range") } return try JSONDecoder().decode(String.self, from: Data(normalized[range].utf8)) } } }