i18n and Localization skill for Claude Code

#!/usr/bin/env python3
"""Check translation files against a base locale (stdlib only).

Supported layouts (JSON, nested objects allowed):
  locales/en.json, locales/de.json                 -> one file per locale
  locales/en/common.json, locales/de/common.json   -> one folder per locale, files are namespaces

Checks per non-base locale:
  - missing keys (present in base, absent in locale)        -> error
  - extra keys (absent in base)                             -> warning
  - empty values                                            -> error
  - placeholder mismatch: ICU {name} / {n, plural, ...} and i18next {{name}} arguments -> error
  - ICU plural/select without an "other" branch             -> error
  - values identical to base (possible untranslated)        -> info, with --show-untranslated

Usage:
  python3 check_locales.py LOCALES_DIR [--base en] [--show-untranslated] [--warn-extra-as-error]
Exit 1 if any error, 2 on bad input.
"""
import argparse
import json
import os
import re
import sys


def flatten(obj, prefix=""):
    out = {}
    if isinstance(obj, dict):
        for k, v in obj.items():
            out.update(flatten(v, f"{prefix}.{k}" if prefix else str(k)))
    elif isinstance(obj, list):
        for i, v in enumerate(obj):
            out.update(flatten(v, f"{prefix}[{i}]"))
    else:
        out[prefix] = obj
    return out


def load_layout(root):
    entries = sorted(os.listdir(root))
    files = [e for e in entries if e.endswith(".json") and os.path.isfile(os.path.join(root, e))]
    dirs = [e for e in entries if os.path.isdir(os.path.join(root, e)) and not e.startswith(".")]
    locales = {}
    if files:
        for f in files:
            with open(os.path.join(root, f), encoding="utf-8") as fh:
                locales[f[:-5]] = flatten(json.load(fh))
    elif dirs:
        for d in dirs:
            merged = {}
            for f in sorted(os.listdir(os.path.join(root, d))):
                if f.endswith(".json"):
                    with open(os.path.join(root, d, f), encoding="utf-8") as fh:
                        merged.update(flatten(json.load(fh), f[:-5]))
            locales[d] = merged
    return locales


class ICUError(Exception):
    pass


def icu_args(msg: str):
    """Return (set of argument names, list of problems) for an ICU message string."""
    names, problems = set(), []
    for m in re.finditer(r"\{\{\s*([\w.-]+)", msg):          # i18next interpolation
        names.add(m.group(1))
    msg = re.sub(r"\{\{.*?\}\}", "", msg)

    def skip_quoted(s, i):
        # ICU: '' is a literal apostrophe; '{...}' quotes syntax characters
        if s.startswith("''", i):
            return i + 2
        if i + 1 < len(s) and s[i + 1] in "{}#|":
            j = s.find("'", i + 1)
            return len(s) if j == -1 else j + 1
        return i + 1

    def parse_message(s, i, stop_at_brace):
        while i < len(s):
            c = s[i]
            if c == "'":
                i = skip_quoted(s, i); continue
            if c == "{":
                i = parse_arg(s, i + 1); continue
            if c == "}":
                if stop_at_brace:
                    return i
                raise ICUError("unbalanced '}'")
            i += 1
        if stop_at_brace:
            raise ICUError("missing '}'")
        return i

    def parse_arg(s, i):
        m = re.compile(r"\s*([\w.-]+)\s*").match(s, i)
        if not m:
            raise ICUError(f"bad argument at {i}")
        names.add(m.group(1)); i = m.end()
        if i < len(s) and s[i] == "}":
            return i + 1
        if i >= len(s) or s[i] != ",":
            raise ICUError(f"expected ',' or '}}' after {m.group(1)}")
        m2 = re.compile(r",\s*(\w+)\s*").match(s, i)
        if not m2:
            raise ICUError("missing argument type")
        typ = m2.group(1); i = m2.end()
        if typ in ("plural", "selectordinal", "select"):
            if i < len(s) and s[i] == ",":
                i += 1
            keys = []
            while True:
                m3 = re.compile(r"\s*(offset:\s*\d+\s*)?").match(s, i); i = m3.end()
                if i < len(s) and s[i] == "}":
                    break
                m4 = re.compile(r"\s*(=?[\w-]+)\s*\{").match(s, i)
                if not m4:
                    raise ICUError(f"bad {typ} option near: {s[i:i + 20]!r}")
                keys.append(m4.group(1)); i = m4.end()
                i = parse_message(s, i, True) + 1
            if "other" not in keys:
                problems.append(f"{typ} without 'other' branch")
            return i + 1
        depth = 1                                     # number/date/time/etc: skip style
        while i < len(s) and depth:
            depth += {"{": 1, "}": -1}.get(s[i], 0); i += 1
        if depth:
            raise ICUError("missing '}'")
        return i

    try:
        parse_message(msg, 0, False)
    except ICUError as e:
        problems.append(f"ICU syntax: {e}")
    return names, problems


def main() -> int:
    ap = argparse.ArgumentParser(description="Check locale files against a base locale")
    ap.add_argument("root")
    ap.add_argument("--base", default="en")
    ap.add_argument("--show-untranslated", action="store_true")
    ap.add_argument("--warn-extra-as-error", action="store_true")
    args = ap.parse_args()

    if not os.path.isdir(args.root):
        print(f"error: {args.root} is not a directory", file=sys.stderr); return 2
    try:
        locales = load_layout(args.root)
    except (OSError, json.JSONDecodeError) as e:
        print(f"error: {e}", file=sys.stderr); return 2
    if args.base not in locales:
        print(f"error: base locale '{args.base}' not found; found {sorted(locales)}", file=sys.stderr); return 2

    base = locales[args.base]
    errors = warnings = 0
    base_args = {}
    for k, v in base.items():
        if isinstance(v, str):
            names, probs = icu_args(v)
            base_args[k] = names
            for p in probs:
                print(f"ERROR [{args.base}] {k}: {p}"); errors += 1

    for loc in sorted(locales):
        if loc == args.base:
            continue
        msgs = locales[loc]
        missing = sorted(set(base) - set(msgs))
        extra = sorted(set(msgs) - set(base))
        for k in missing:
            print(f"ERROR [{loc}] missing key: {k}"); errors += 1
        for k in extra:
            level = "ERROR" if args.warn_extra_as_error else "WARN "
            print(f"{level} [{loc}] extra key: {k}")
            errors += args.warn_extra_as_error; warnings += not args.warn_extra_as_error
        for k in sorted(set(base) & set(msgs)):
            v = msgs[k]
            if isinstance(v, str):
                if not v.strip():
                    print(f"ERROR [{loc}] empty value: {k}"); errors += 1; continue
                names, probs = icu_args(v)
                for p in probs:
                    print(f"ERROR [{loc}] {k}: {p}"); errors += 1
                want = base_args.get(k, set())
                if names != want:
                    miss, add = sorted(want - names), sorted(names - want)
                    detail = "; ".join(x for x in (f"missing {miss}" if miss else "", f"unknown {add}" if add else "") if x)
                    print(f"ERROR [{loc}] placeholder mismatch in {k}: {detail}"); errors += 1
                if args.show_untranslated and v == base.get(k) and len(v) > 3:
                    print(f"INFO  [{loc}] identical to base: {k}")
        print(f"--- {loc}: {len(msgs)} keys, {len(missing)} missing, {len(extra)} extra")

    print(f"\nlocales: {len(locales)} (base {args.base}, {len(base)} keys)  errors: {errors}  warnings: {warnings}")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())