app-localizer 1.0.1__py3-none-any.whl

app_localizer/__init__.py

@@ -0,0 +1,19 @@
+"""Translate Apple String Catalog files."""
+
+__all__ = [
+    "StringsCatalogTranslator",
+    "TranslationConfig",
+]
+
+
+def __getattr__(name):
+    if name in __all__:
+        from app_localizer.xcstrings import StringsCatalogTranslator, TranslationConfig
+
+        exports = {
+            "StringsCatalogTranslator": StringsCatalogTranslator,
+            "TranslationConfig": TranslationConfig,
+        }
+        return exports[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

app_localizer/catalog.py

@@ -0,0 +1,597 @@
+"""Utilities for reading and mutating Apple String Catalog files."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from copy import deepcopy
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+import re
+from typing import Any, Dict, Iterator, Mapping, Optional
+
+from app_localizer.cldr import ordered_categories, required_cardinal_categories
+from app_localizer.fileio import atomic_write_json
+
+JsonObject = Dict[str, Any]
+
+PLURAL_VARIATION_KEY = "plural"
+CARDINAL_CATEGORIES = frozenset({"zero", "one", "two", "few", "many", "other"})
+
+PRINTF_PLACEHOLDER_PATTERN = re.compile(
+    r"%(?:\d+\$)?[-+#0 ]*(?:\*|\d+)?(?:\.(?:\*|\d+))?"
+    r"(?:hh|h|ll|l|L|z|j|t)?[@diuoxXfFeEgGaAcsp%]"
+)
+POSITIONAL_PRINTF_PATTERN = re.compile(r"%\d+\$")
+SWIFT_INTERPOLATION_PATTERN = re.compile(r"\\\([^)]+\)")
+SUBSTITUTION_PLACEHOLDER_PATTERN = re.compile(r"%(?:\d+\$)?#@\w+@|%arg\b")
+
+
+class CatalogError(Exception):
+    """Raised when a string catalog is missing required structure."""
+
+
+@dataclass
+class StringUnitReference:
+    """A mutable reference to a string unit inside a localization tree."""
+
+    key_path: str
+    string_unit: JsonObject
+
+
+def load_catalog(path: Path) -> JsonObject:
+    """Load and validate a string catalog from disk."""
+    if not path.exists():
+        raise CatalogError(f"Catalog does not exist: {path}")
+    if not path.is_file():
+        raise CatalogError(f"Catalog path is not a file: {path}")
+
+    try:
+        with path.open("r", encoding="utf-8") as file:
+            catalog = json.load(file, object_pairs_hook=_object_rejecting_duplicate_keys)
+    except json.JSONDecodeError as error:
+        raise CatalogError(f"Catalog is not valid JSON: {error}") from error
+    except ValueError as error:
+        raise CatalogError(f"Catalog is not valid: {error}") from error
+    except OSError as error:
+        raise CatalogError(f"Catalog could not be read: {error}") from error
+
+    if not isinstance(catalog, dict):
+        raise CatalogError("Catalog root must be a JSON object.")
+    if not isinstance(catalog.get("sourceLanguage"), str):
+        raise CatalogError("Catalog must contain a string sourceLanguage.")
+    if not isinstance(catalog.get("strings"), dict):
+        raise CatalogError("Catalog must contain a strings object.")
+
+    version = catalog.get("version")
+    if version is not None and (
+        not isinstance(version, str) or version.split(".", 1)[0] != "1"
+    ):
+        raise CatalogError(
+            f"Catalog version {version!r} is not supported. Supported versions: 1.x."
+        )
+
+    return catalog
+
+
+def write_catalog(path: Path, catalog: Mapping[str, Any]) -> None:
+    """Write a catalog atomically using Xcode-style JSON spacing."""
+    try:
+        atomic_write_json(path, catalog)
+    except OSError as error:
+        raise CatalogError(f"Catalog could not be written: {error}") from error
+
+
+def ensure_source_localizations(catalog: JsonObject) -> bool:
+    """Ensure every string has a usable source localization."""
+    source_language = catalog["sourceLanguage"]
+    changed = False
+
+    for key, string_data in catalog["strings"].items():
+        if not isinstance(string_data, dict):
+            raise CatalogError(f"String entry {key!r} must be an object.")
+
+        localizations = string_data.get("localizations")
+        if not isinstance(localizations, dict):
+            localizations = {}
+            string_data["localizations"] = localizations
+            changed = True
+
+        source_localization = localizations.get(source_language)
+        if not isinstance(source_localization, dict) or not string_units_by_key_path(
+            source_localization, key
+        ):
+            localizations[source_language] = {
+                "stringUnit": {
+                    "state": "translated",
+                    "value": key,
+                }
+            }
+            changed = True
+
+    return changed
+
+
+def ensure_target_localization(
+    string_data: JsonObject,
+    source_language: str,
+    target_language: str,
+    fallback_value: str,
+) -> JsonObject:
+    """Return a target localization that contains every source string unit."""
+    localizations = string_data["localizations"]
+    source_localization = localizations.get(source_language)
+    if not isinstance(source_localization, dict):
+        source_localization = {
+            "stringUnit": {
+                "state": "translated",
+                "value": fallback_value,
+            }
+        }
+
+    target_localization = localizations.get(target_language)
+    if isinstance(target_localization, dict):
+        reconcile_target_localization(target_localization, source_localization)
+        return target_localization
+
+    target_localization = clone_localization_for_translation(source_localization)
+    localizations[target_language] = target_localization
+    return target_localization
+
+
+def reconcile_target_localization(
+    target_localization: JsonObject,
+    source_localization: Mapping[str, Any],
+) -> bool:
+    """Add missing source string units to an existing target localization."""
+    return _merge_missing_units(target_localization, source_localization)
+
+
+def clone_localization_for_translation(localization: Mapping[str, Any]) -> JsonObject:
+    """Deep-copy a localization and mark every string unit as new."""
+    cloned = deepcopy(dict(localization))
+    _mark_translatable_units_new(cloned)
+    return cloned
+
+
+def string_units_by_key_path(localization: Mapping[str, Any], key_path: str) -> Dict[str, JsonObject]:
+    """Return string units keyed by their catalog key path."""
+    return {
+        reference.key_path: reference.string_unit
+        for reference in iter_string_units(localization, key_path)
+    }
+
+
+def plural_category_for_key_path(key_path: str) -> Optional[str]:
+    """Return the CLDR plural category a key path ends in, or ``None``.
+
+    A plural unit's key path ends in ``.plural.<category>`` (for example
+    ``key.plural.few`` or ``key.device.iphone.plural.few``).
+    """
+    segments = key_path.split(".")
+    if (
+        len(segments) >= 2
+        and segments[-2] == PLURAL_VARIATION_KEY
+        and segments[-1] in CARDINAL_CATEGORIES
+    ):
+        return segments[-1]
+    return None
+
+
+def expand_plural_categories(localization: JsonObject, target_language: str) -> bool:
+    """Add plural categories the target language requires but the source omits.
+
+    Walks the localization's variation tree, including plural maps nested under a
+    device axis and inside substitutions. Each missing CLDR cardinal category is
+    added by cloning the plural map's ``other`` unit and marking the clone new, so
+    the surrounding translate loop fills it. Never touches non-plural axes such as
+    ``device``, never removes a category, and is a no-op when the target language
+    has no curated rule. Returns whether anything was added.
+    """
+    required = required_cardinal_categories(target_language)
+    if required is None:
+        return False
+    return _expand_plural_in_node(localization, required)
+
+
+def required_source_units_for_target(
+    source_localization: Mapping[str, Any],
+    key_path: str,
+    target_language: str,
+) -> Dict[str, JsonObject]:
+    """Source string units to translate for the target, by key path.
+
+    This is the source's own units plus, for every plural map, the categories the
+    target language requires but the source lacks. Each added category points at
+    the source's ``other`` unit, the correct base text for producing that
+    category's form. With no curated rule for the target, this is exactly the
+    source's units.
+    """
+    required = required_cardinal_categories(target_language)
+    units: Dict[str, JsonObject] = {}
+    _collect_required_source_units(source_localization, key_path, required, units)
+    return units
+
+
+def iter_string_units(localization: Mapping[str, Any], key_path: str) -> Iterator[StringUnitReference]:
+    """Yield mutable string units in a localization or variation tree."""
+    if not isinstance(localization, dict):
+        return
+
+    string_unit = localization.get("stringUnit")
+    if isinstance(string_unit, dict):
+        yield StringUnitReference(key_path=key_path, string_unit=string_unit)
+
+    variations = localization.get("variations")
+    if isinstance(variations, dict):
+        yield from _iter_variation_units(variations, key_path)
+
+    substitutions = localization.get("substitutions")
+    if isinstance(substitutions, dict):
+        yield from _iter_substitution_units(substitutions, key_path)
+
+
+def placeholders_match(source: str, translation: str) -> bool:
+    """Return whether a translation preserves source placeholders exactly."""
+    source_parts = _extract_placeholders(source)
+    translation_parts = _extract_placeholders(translation)
+    return (
+        Counter(source_parts.substitutions) == Counter(translation_parts.substitutions)
+        and Counter(source_parts.swift_interpolations)
+        == Counter(translation_parts.swift_interpolations)
+        and _printf_placeholders_match(source_parts.printf, translation_parts.printf)
+    )
+
+
+@dataclass(frozen=True)
+class _PlaceholderParts:
+    """Placeholder tokens grouped by their runtime safety rules."""
+
+    substitutions: list[str]
+    printf: list[str]
+    swift_interpolations: list[str]
+
+
+def source_fingerprint(catalog: Mapping[str, Any]) -> str:
+    """Hash only source text and translation-relevant metadata."""
+    source_language = catalog["sourceLanguage"]
+    strings = catalog["strings"]
+    payload: JsonObject = {
+        "sourceLanguage": source_language,
+        "strings": {},
+    }
+
+    for key, string_data in strings.items():
+        if not isinstance(string_data, dict):
+            continue
+
+        relevant_data = {
+            name: deepcopy(value)
+            for name, value in string_data.items()
+            if name != "localizations"
+        }
+        relevant_data["localizations"] = {
+            source_language: deepcopy(
+                string_data.get("localizations", {}).get(source_language)
+            )
+        }
+        payload["strings"][key] = relevant_data
+
+    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    return sha256(encoded).hexdigest()
+
+
+# This walker and its two siblings, _expand_plural_in_variations and
+# _collect_required_variation_units, share the same leaf-vs-axis test and key-path
+# construction. They must stay aligned: if the collector yields a key path the
+# expander does not also create in the target, translation reports a missing
+# target unit. ExpandPluralCategoriesTests and RequiredSourceUnitsForTargetTests
+# guard the alignment.
+def _iter_variation_units(variations: Mapping[str, Any], key_path: str) -> Iterator[StringUnitReference]:
+    for name, value in variations.items():
+        if not isinstance(value, dict):
+            continue
+
+        child_key_path = f"{key_path}.{name}" if key_path else name
+        if "stringUnit" in value or "variations" in value:
+            yield from iter_string_units(value, child_key_path)
+        else:
+            yield from _iter_variation_units(value, child_key_path)
+
+
+def _expand_plural_in_node(node: Any, required: frozenset) -> bool:
+    if not isinstance(node, dict):
+        return False
+
+    changed = False
+    variations = node.get("variations")
+    if isinstance(variations, dict):
+        changed = _expand_plural_in_variations(variations, required) or changed
+
+    substitutions = node.get("substitutions")
+    if isinstance(substitutions, dict):
+        for substitution in substitutions.values():
+            changed = _expand_plural_in_node(substitution, required) or changed
+
+    return changed
+
+
+# Mirrors _iter_variation_units; keep the leaf-vs-axis test and recursion aligned.
+def _expand_plural_in_variations(variations: Mapping[str, Any], required: frozenset) -> bool:
+    changed = False
+    for name, value in variations.items():
+        if not isinstance(value, dict):
+            continue
+        if "stringUnit" in value or "variations" in value:
+            changed = _expand_plural_in_node(value, required) or changed
+            continue
+
+        # value is a nested axis map keyed by category or device name.
+        if name == PLURAL_VARIATION_KEY:
+            changed = _expand_plural_map(value, required) or changed
+        for child in list(value.values()):
+            changed = _expand_plural_in_node(child, required) or changed
+    return changed
+
+
+def _expand_plural_map(plural_map: JsonObject, required: frozenset) -> bool:
+    other = plural_map.get("other")
+    if not isinstance(other, dict) or not isinstance(other.get("stringUnit"), dict):
+        return False
+
+    changed = False
+    for category in ordered_categories(required):
+        if category == "other" or category in plural_map:
+            continue
+        plural_map[category] = clone_localization_for_translation(other)
+        changed = True
+    return changed
+
+
+def _collect_required_source_units(
+    node: Any,
+    key_path: str,
+    required: Optional[frozenset],
+    out: Dict[str, JsonObject],
+) -> None:
+    if not isinstance(node, dict):
+        return
+
+    string_unit = node.get("stringUnit")
+    if isinstance(string_unit, dict):
+        out[key_path] = string_unit
+
+    variations = node.get("variations")
+    if isinstance(variations, dict):
+        _collect_required_variation_units(variations, key_path, required, out)
+
+    substitutions = node.get("substitutions")
+    if isinstance(substitutions, dict):
+        for name, substitution in substitutions.items():
+            child_key_path = (
+                f"{key_path}.substitutions.{name}" if key_path else f"substitutions.{name}"
+            )
+            _collect_required_source_units(substitution, child_key_path, required, out)
+
+
+# Mirrors _iter_variation_units; keep the leaf-vs-axis test and key paths aligned.
+def _collect_required_variation_units(
+    variations: Mapping[str, Any],
+    key_path: str,
+    required: Optional[frozenset],
+    out: Dict[str, JsonObject],
+) -> None:
+    for name, value in variations.items():
+        if not isinstance(value, dict):
+            continue
+
+        child_key_path = f"{key_path}.{name}" if key_path else name
+        if "stringUnit" in value or "variations" in value:
+            _collect_required_source_units(value, child_key_path, required, out)
+            continue
+
+        # value is a nested axis map keyed by category or device name.
+        _collect_required_variation_units(value, child_key_path, required, out)
+        if name == PLURAL_VARIATION_KEY and required is not None:
+            _synthesize_target_only_plurals(value, child_key_path, required, out)
+
+
+def _synthesize_target_only_plurals(
+    plural_map: Mapping[str, Any],
+    key_path: str,
+    required: frozenset,
+    out: Dict[str, JsonObject],
+) -> None:
+    other = plural_map.get("other")
+    other_unit = other.get("stringUnit") if isinstance(other, dict) else None
+    if not isinstance(other_unit, dict):
+        return
+
+    for category in required:
+        if category == "other" or category in plural_map:
+            continue
+        child_key_path = f"{key_path}.{category}" if key_path else category
+        out[child_key_path] = other_unit
+
+
+def _object_rejecting_duplicate_keys(pairs: Any) -> JsonObject:
+    obj: JsonObject = {}
+    for key, value in pairs:
+        if key in obj:
+            raise ValueError(f"Duplicate key {key!r} in JSON object.")
+        obj[key] = value
+    return obj
+
+
+def _iter_substitution_units(substitutions: Mapping[str, Any], key_path: str) -> Iterator[StringUnitReference]:
+    for name, substitution in substitutions.items():
+        if not isinstance(substitution, dict):
+            continue
+
+        child_key_path = f"{key_path}.substitutions.{name}" if key_path else f"substitutions.{name}"
+        yield from iter_string_units(substitution, child_key_path)
+
+
+def _extract_placeholders(value: str) -> _PlaceholderParts:
+    substitutions = SUBSTITUTION_PLACEHOLDER_PATTERN.findall(value)
+    remainder = SUBSTITUTION_PLACEHOLDER_PATTERN.sub(" ", value)
+    return _PlaceholderParts(
+        substitutions=substitutions,
+        printf=PRINTF_PLACEHOLDER_PATTERN.findall(remainder),
+        swift_interpolations=SWIFT_INTERPOLATION_PATTERN.findall(remainder),
+    )
+
+
+def _printf_placeholders_match(source: list[str], translation: list[str]) -> bool:
+    source_escaped_percents = source.count("%%")
+    translation_escaped_percents = translation.count("%%")
+    if source_escaped_percents != translation_escaped_percents:
+        return False
+
+    source_arguments = [placeholder for placeholder in source if placeholder != "%%"]
+    translation_arguments = [placeholder for placeholder in translation if placeholder != "%%"]
+    if _all_printf_arguments_are_positional(source_arguments):
+        return Counter(source_arguments) == Counter(translation_arguments)
+    return source_arguments == translation_arguments
+
+
+def _all_printf_arguments_are_positional(placeholders: list[str]) -> bool:
+    return bool(placeholders) and all(
+        POSITIONAL_PRINTF_PATTERN.match(placeholder) is not None
+        for placeholder in placeholders
+    )
+
+
+def _clone_string_unit(source_string_unit: Mapping[str, Any]) -> JsonObject:
+    cloned = deepcopy(dict(source_string_unit))
+    cloned["state"] = "new"
+    return cloned
+
+
+def _mark_translatable_units_new(node: JsonObject) -> None:
+    string_unit = node.get("stringUnit")
+    if isinstance(string_unit, dict):
+        string_unit["state"] = "new"
+
+    variations = node.get("variations")
+    if isinstance(variations, dict):
+        _mark_variation_units_new(variations)
+
+    substitutions = node.get("substitutions")
+    if isinstance(substitutions, dict):
+        for substitution in substitutions.values():
+            if isinstance(substitution, dict):
+                _mark_translatable_units_new(substitution)
+
+    if (
+        not isinstance(string_unit, dict)
+        and not isinstance(variations, dict)
+        and not isinstance(substitutions, dict)
+    ):
+        _mark_variation_units_new(node)
+
+
+def _mark_variation_units_new(variations: Mapping[str, Any]) -> None:
+    for value in variations.values():
+        if not isinstance(value, dict):
+            continue
+        if "stringUnit" in value or "variations" in value:
+            _mark_translatable_units_new(value)
+        else:
+            _mark_variation_units_new(value)
+
+
+def _merge_missing_units(target_node: JsonObject, source_node: Mapping[str, Any]) -> bool:
+    changed = False
+
+    source_string_unit = source_node.get("stringUnit")
+    source_variations = source_node.get("variations")
+
+    if isinstance(source_string_unit, dict):
+        if "variations" in target_node:
+            del target_node["variations"]
+            changed = True
+        if not isinstance(target_node.get("stringUnit"), dict):
+            target_node["stringUnit"] = _clone_string_unit(source_string_unit)
+            changed = True
+    elif isinstance(source_variations, dict):
+        if "stringUnit" in target_node:
+            del target_node["stringUnit"]
+            changed = True
+
+        target_variations = target_node.get("variations")
+        if not isinstance(target_variations, dict):
+            target_variations = {}
+            target_node["variations"] = target_variations
+            changed = True
+
+        changed = _merge_missing_variations(target_variations, source_variations) or changed
+
+    return _merge_missing_substitutions(target_node, source_node) or changed
+
+
+def _merge_missing_substitutions(target_node: JsonObject, source_node: Mapping[str, Any]) -> bool:
+    source_substitutions = source_node.get("substitutions")
+    if not isinstance(source_substitutions, dict):
+        if "substitutions" in target_node:
+            del target_node["substitutions"]
+            return True
+        return False
+
+    changed = False
+    target_substitutions = target_node.get("substitutions")
+    if not isinstance(target_substitutions, dict):
+        target_substitutions = {}
+        target_node["substitutions"] = target_substitutions
+        changed = True
+
+    for name, source_substitution in source_substitutions.items():
+        if not isinstance(source_substitution, dict):
+            continue
+
+        target_substitution = target_substitutions.get(name)
+        if not isinstance(target_substitution, dict):
+            target_substitutions[name] = clone_localization_for_translation(source_substitution)
+            changed = True
+            continue
+
+        for metadata_key in ("argNum", "formatSpecifier"):
+            if metadata_key not in source_substitution:
+                continue
+            if target_substitution.get(metadata_key) != source_substitution[metadata_key]:
+                target_substitution[metadata_key] = deepcopy(source_substitution[metadata_key])
+                changed = True
+
+        changed = _merge_missing_units(target_substitution, source_substitution) or changed
+
+    for name in list(target_substitutions):
+        if not isinstance(source_substitutions.get(name), dict):
+            del target_substitutions[name]
+            changed = True
+
+    return changed
+
+
+def _merge_missing_variations(
+    target_variations: JsonObject,
+    source_variations: Mapping[str, Any],
+) -> bool:
+    changed = False
+
+    for name, source_child in source_variations.items():
+        if not isinstance(source_child, dict):
+            continue
+
+        target_child = target_variations.get(name)
+        if not isinstance(target_child, dict):
+            target_variations[name] = clone_localization_for_translation(source_child)
+            changed = True
+            continue
+
+        if "stringUnit" in source_child or "variations" in source_child:
+            changed = _merge_missing_units(target_child, source_child) or changed
+        else:
+            changed = _merge_missing_variations(target_child, source_child) or changed
+
+    return changed