Skip to content

armgit / peel

Public Imported from GitHub
0

Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.

10.0 KB
Raw Blame
"""Keeps the string catalogs in step with the strings in the code.

Run after building the Debug configuration into `build/DerivedData`:
    python3 Scripts/sync_localizations.py            writes the catalogs
    python3 Scripts/sync_localizations.py --check    writes nothing, says what would change, exits 1 if anything would

There are six catalogs in `Localization/`: Localizable and InfoPlist for the app and for the Finder extension,
AppShortcuts (the phrases Siri and Spotlight match), and DebugBuild, the app's strings that only a Debug build shows,
which the Release configuration leaves out. InfoPlist holds the text macOS shows from an Info.plist, such as the app's
permission prompts and the copyright in Finder's Info window. Apple's `xcstringstool sync` updates Localizable,
AppShortcuts, and DebugBuild from the build's `.stringsdata` files. It adds new strings. A string that is not in the
build output is removed when it has no translations, and otherwise marked stale with its translations kept. The tool
picks the strings table by the catalog's file name, so each catalog is synced on a copy with the same name. InfoPlist
has no `.stringsdata`: its English is read from the target's Info.plist in `Support/`, and the bundle's name is marked
as never translated.

The script stops instead of guessing. It exits when there is no build output, because a sync against nothing would
treat every string as gone, and when the build is older than the code, because a sync against it would miss what
changed since. The app would still build and launch, so the damage could be committed unnoticed. It also exits
when a run would remove or mark stale more than a quarter of a catalog and more than one string, or all of it.
Every catalog is worked out before any is written, so a stop leaves them all as they were. Run with `--force` to
go ahead anyway.
"""
import argparse, json, pathlib, platform, plistlib, shutil, subprocess, sys, tempfile

PROJECT = pathlib.Path(__file__).resolve().parent.parent
INTERMEDIATES = PROJECT / "build/DerivedData/Build/Intermediates.noindex/Peel.build/Debug"
LOCALIZATION = PROJECT / "Localization"
SYNCED = [
    ("Peel", LOCALIZATION / "Peel/Localizable.xcstrings"),
    ("Peel", LOCALIZATION / "Peel/AppShortcuts.xcstrings"),
    ("Peel", LOCALIZATION / "Peel/DebugBuild.xcstrings"),
    ("PeelFinder", LOCALIZATION / "PeelFinder/Localizable.xcstrings"),
]
INFO = [
    (PROJECT / "Support/Peel-Info.plist", LOCALIZATION / "Peel/InfoPlist.xcstrings"),
    (PROJECT / "Support/PeelFinder-Info.plist", LOCALIZATION / "PeelFinder/InfoPlist.xcstrings"),
]
NAMES = ["CFBundleDisplayName", "CFBundleName"]
# Anything else is refused before a catalog is touched: a mistyped --check would otherwise write them all.
parser = argparse.ArgumentParser(
    description="Keeps the string catalogs in step with the strings in the code.", allow_abbrev=False
)
parser.add_argument(
    "--check", action="store_true", help="write nothing, say what would change, exit 1 if anything would"
)
parser.add_argument(
    "--force", action="store_true",
    help="go ahead even when a run would remove or mark stale over a quarter of a catalog",
)
options = parser.parse_args()
CHECK = options.check
FORCE = options.force


def empty_catalog():
    return {"sourceLanguage": "en", "strings": {}, "version": "1.0"}


# Removing or marking stale more than this share of a catalog suggests the build output is not from this code.
MOST_OF_IT = 0.25


def keys(catalog):
    return catalog.get("strings", {})


def stale(entry):
    return entry.get("extractionState") == "stale"


def write(path, catalog):
    text = json.dumps(catalog, ensure_ascii=False, indent=2, sort_keys=True, separators=(",", " : "))
    path.write_text(text + "\n", encoding="utf-8")


def report(name, before, after):
    """Prints how two catalogs differ and returns True if they do. Exits if too many strings would go: more than a
    quarter of them and more than one, or all of them."""
    old, new = keys(before), keys(after)
    added = sorted(set(new) - set(old))
    removed = sorted(set(old) - set(new))
    went_stale = sorted(k for k in new if stale(new[k]) and k in old and not stale(old[k]))
    changed = sorted(k for k in new if k in old and new[k] != old[k] and k not in went_stale)
    differs = json.dumps(before, sort_keys=True) != json.dumps(after, sort_keys=True)
    print(f"{name}: {len(new)} strings, {len(added)} added, {len(removed)} removed, {len(went_stale)} marked stale, "
          f"{len(changed)} changed")
    for kind, found in (("added", added), ("removed", removed), ("stale", went_stale), ("changed", changed)):
        for key in found:
            print(f"  {kind}: {key!r}")
    going = len(removed) + len(went_stale)
    if old and (going > max(1, MOST_OF_IT * len(old)) or going == len(old)) and not FORCE:
        sys.exit(f"{name}: {going} of {len(old)} strings would go. Check the build, then run with --force.")
    return differs


def stringsdata(target):
    """The `.stringsdata` files the last build wrote for `target` on this Mac's architecture. Exits when that build
    is older than the code: a source changed or added since would leave its strings out or out of date."""
    folder = INTERMEDIATES / f"{target}.build/Objects-normal/{platform.machine()}"
    listed = folder / f"{target}.SwiftFileList"
    if not listed.exists():
        sys.exit(f"no build of {target} under {INTERMEDIATES}: build Debug into build/DerivedData first")
    sources = [pathlib.Path(line) for line in listed.read_text(encoding="utf-8").splitlines() if line]
    unbuilt = sorted(set((PROJECT / target).rglob("*.swift")) - set(sources))

    # The build writes some of a source's outputs each time it looks at it after a change, not always the same ones:
    # a change to a comment leaves the object and the strings as they were.
    def built_since_changed(source):
        outputs = [folder / f"{source.stem}{kind}" for kind in (".d", ".swiftdeps", ".o", ".stringsdata")]
        times = [output.stat().st_mtime for output in outputs if output.exists()]
        return (folder / f"{source.stem}.stringsdata").exists() and max(times) >= source.stat().st_mtime

    changed = [source for source in sources if not built_since_changed(source)]
    if unbuilt or changed:
        names = ", ".join(path.name for path in unbuilt + changed)
        sys.exit(f"{target} changed since its last build ({names}): build Debug into build/DerivedData first")
    # A file that is no source's, such as the App Shortcuts phrases, counts only when this build wrote it: one left
    # by a source since removed is older than the list of sources.
    stems = {source.stem for source in sources}
    others = [path for path in folder.glob("*.stringsdata")
              if path.stem not in stems and path.stat().st_mtime >= listed.stat().st_mtime]
    return [str(folder / f"{stem}.stringsdata") for stem in sorted(stems)] + [str(path) for path in sorted(others)]


def synced(target, catalog_path):
    """Returns the catalog as `xcstringstool sync` would leave it, syncing a copy in a temporary folder."""
    files = stringsdata(target)
    with tempfile.TemporaryDirectory() as folder:
        copy = pathlib.Path(folder) / catalog_path.name
        if catalog_path.exists():
            shutil.copyfile(catalog_path, copy)
        else:
            write(copy, empty_catalog())
        subprocess.run(["xcrun", "xcstringstool", "sync", str(copy), "--stringsdata", *files], check=True)
        return json.loads(copy.read_text(encoding="utf-8"))


def info_plist(path, current):
    """Returns an InfoPlist catalog: the English from the Info.plist at `path`, with every existing translation kept.
    When the English changed, each translation still says the old text, so it is marked for review, which the
    catalog tests refuse until it is translated again."""
    plist = plistlib.loads(path.read_bytes())
    strings = {}
    old = keys(current)
    # The keys whose text macOS shows: the permission prompts, and the copyright in Finder's Info window.
    shown = sorted(key for key in plist if key.endswith("UsageDescription") or key == "NSHumanReadableCopyright")
    for key in shown:
        entry = dict(old.get(key, {}))
        localizations = dict(entry.get("localizations", {}))
        english = localizations.get("en", {}).get("stringUnit", {}).get("value")
        if english is not None and english != plist[key]:
            print(f"  changed in English, translations to review: {key}")
            localizations = {
                language: {"stringUnit": {**value["stringUnit"], "state": "needs_review"}}
                if "stringUnit" in value else value
                for language, value in localizations.items()
            }
        localizations["en"] = {"stringUnit": {"state": "new", "value": plist[key]}}
        entry["localizations"] = localizations
        entry["extractionState"] = "extracted_with_value"
        entry.pop("shouldTranslate", None)
        strings[key] = entry
    for key in NAMES:
        entry = {k: v for k, v in old.get(key, {}).items() if k == "comment"}
        entry["shouldTranslate"] = False
        strings[key] = entry
    return {"sourceLanguage": "en", "strings": strings, "version": current.get("version", "1.0")}


# Every catalog is worked out and judged before any is written, so a refusal or an error on one leaves them all
# as they were.
results = []
for target, path in SYNCED:
    before = json.loads(path.read_text(encoding="utf-8")) if path.exists() else empty_catalog()
    after = synced(target, path)
    results.append((path, after, report(f"{target} {path.stem}", before, after)))
for plist, path in INFO:
    before = json.loads(path.read_text(encoding="utf-8")) if path.exists() else empty_catalog()
    after = info_plist(plist, before)
    results.append((path, after, report(f"{path.parent.name} InfoPlist", before, after)))

differs = any(changed for _, _, changed in results)
if not CHECK:
    for path, after, changed in results:
        if changed:
            write(path, after)

if CHECK and differs:
    sys.exit("the catalogs are not in step with the code: run python3 Scripts/sync_localizations.py")