localediff 0.1.0__tar.gz

localediff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 localediff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

localediff-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: localediff
+Version: 0.1.0
+Summary: Find drift between i18n locale files — missing keys, CLDR-aware plural gaps, empty values. Framework-agnostic, zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/localediff-py
+Project-URL: Repository, https://github.com/jjdoor/localediff-py
+Project-URL: Issues, https://github.com/jjdoor/localediff-py/issues
+Keywords: i18n,l10n,locale,translation,missing-translations,drift,diff,i18next,cli,ci,pluralization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# localediff
+
+**Find drift between your i18n locale files — before your users do.** You add a
+string to `en.json`, ship it, and three weeks later notice `fr.json` and
+`zh.json` were never updated. `localediff` catches that in CI: missing keys,
+plural forms a language actually needs, and keys that exist but were left blank.
+Framework-agnostic, **zero dependencies**.
+
+```bash
+pip install localediff
+localediff ./locales
+```
+
+```
+✗ fr.json
+  missing (1): auth.errors.locked
+  plural  cart.items — has {other}, missing {one}
+  empty   (1): footer.copyright
+  extra   (1): legacy.banner
+
+✓ zh.json — in sync
+
+✗ 1 of 2 file(s) drifted — 1 missing, 1 plural gap(s), 1 empty, 1 extra
+```
+
+## Why another i18n tool
+
+Most existing tools are tied to one framework, need an account, or are heavy
+AST-based linters. `localediff` just reads JSON. It compares **structure**, so it
+works for next-intl, react-intl, i18next, vue-i18n, Django/Flask JSON catalogs,
+or any plain message file — and it ships for **both PyPI and npm** with identical
+behavior.
+
+### It understands plurals per language
+
+This is the part naive "diff two JSON files" scripts get wrong. English has two
+plural forms (`one`, `other`); Chinese has one (`other`); Russian has four
+(`one`, `few`, `many`, `other`). A file with only `items_other` is **correct for
+Chinese** but **broken for French**. `localediff` resolves the required CLDR
+categories from each target's language, so it flags the real bug without crying
+wolf on `zh.json`.
+
+```bash
+# en base: items_one + items_other
+zh.json  →  items_other only   →  ✓ in sync   (Chinese needs only `other`)
+fr.json  →  items_other only   →  ✗ missing {one}
+ru.json  →  items_one + _other →  ✗ missing {few, many}
+```
+
+## Usage
+
+```bash
+# Scan a folder. The base defaults to en.json; everything else is checked.
+localediff ./locales
+
+# Pick a different base language in the folder.
+localediff ./locales --base de
+
+# Compare specific files explicitly.
+localediff --base en.json --check fr.json zh.json
+
+# Shorthand: first file is the base.
+localediff en.json fr.json zh.json
+
+# Machine-readable output for CI gates.
+localediff ./locales --format json
+```
+
+You can also run it as a module: `python -m localediff ./locales`.
+
+## What it checks
+
+| Check | Meaning |
+|-------|---------|
+| **missing** | a key in the base that the target never translated |
+| **plural** | a pluralized key (`key_one`, `key_other`, …) missing a CLDR form the **target language** requires |
+| **empty** | a key present in the target whose value is a blank string |
+| **extra** | a key in the target the base no longer has |
+
+Nested objects are flattened to dot-paths (`auth.errors.locked`); arrays are
+indexed (`steps.0`). Plural keys use the i18next suffix convention
+(`_zero`, `_one`, `_two`, `_few`, `_many`, `_other`). Unknown languages fall back
+to parity with the base, so you never get a confidently-wrong result.
+
+## Options
+
+```
+--base <file|lang>    base/source locale (a file, or a lang stem in dir mode)
+--check <files...>    one or more target locales to compare against the base
+--dir <dir>           scan a directory of *.json locales
+--lang <code>         force the target language for plural rules
+--format text|json    output format (default: text)
+--ignore-missing      don't report missing keys
+--ignore-extra        don't report extra keys
+--ignore-plural       don't report plural gaps
+--ignore-empty        don't report empty values
+-v, --version
+-h, --help
+```
+
+## In CI
+
+`localediff` exits non-zero when anything has drifted:
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | every checked file is in sync |
+| `1` | one or more files have drift |
+| `2` | error (file not found, invalid JSON, bad arguments) |
+
+## Also available for Node
+
+```bash
+npx localediff ./locales
+```
+
+Same checks, same flags, same exit codes — [localediff on npm](https://github.com/jjdoor/localediff).
+
+## Scope
+
+JSON locale files only (the common case). YAML/`.properties`/gettext are not
+supported — parsing them would mean pulling in a dependency, and zero-dep is the
+point. Convert to JSON, or open an issue to discuss.
+
+## License
+
+MIT

localediff-0.1.0/README.md

@@ -0,0 +1,127 @@
+# localediff
+
+**Find drift between your i18n locale files — before your users do.** You add a
+string to `en.json`, ship it, and three weeks later notice `fr.json` and
+`zh.json` were never updated. `localediff` catches that in CI: missing keys,
+plural forms a language actually needs, and keys that exist but were left blank.
+Framework-agnostic, **zero dependencies**.
+
+```bash
+pip install localediff
+localediff ./locales
+```
+
+```
+✗ fr.json
+  missing (1): auth.errors.locked
+  plural  cart.items — has {other}, missing {one}
+  empty   (1): footer.copyright
+  extra   (1): legacy.banner
+
+✓ zh.json — in sync
+
+✗ 1 of 2 file(s) drifted — 1 missing, 1 plural gap(s), 1 empty, 1 extra
+```
+
+## Why another i18n tool
+
+Most existing tools are tied to one framework, need an account, or are heavy
+AST-based linters. `localediff` just reads JSON. It compares **structure**, so it
+works for next-intl, react-intl, i18next, vue-i18n, Django/Flask JSON catalogs,
+or any plain message file — and it ships for **both PyPI and npm** with identical
+behavior.
+
+### It understands plurals per language
+
+This is the part naive "diff two JSON files" scripts get wrong. English has two
+plural forms (`one`, `other`); Chinese has one (`other`); Russian has four
+(`one`, `few`, `many`, `other`). A file with only `items_other` is **correct for
+Chinese** but **broken for French**. `localediff` resolves the required CLDR
+categories from each target's language, so it flags the real bug without crying
+wolf on `zh.json`.
+
+```bash
+# en base: items_one + items_other
+zh.json  →  items_other only   →  ✓ in sync   (Chinese needs only `other`)
+fr.json  →  items_other only   →  ✗ missing {one}
+ru.json  →  items_one + _other →  ✗ missing {few, many}
+```
+
+## Usage
+
+```bash
+# Scan a folder. The base defaults to en.json; everything else is checked.
+localediff ./locales
+
+# Pick a different base language in the folder.
+localediff ./locales --base de
+
+# Compare specific files explicitly.
+localediff --base en.json --check fr.json zh.json
+
+# Shorthand: first file is the base.
+localediff en.json fr.json zh.json
+
+# Machine-readable output for CI gates.
+localediff ./locales --format json
+```
+
+You can also run it as a module: `python -m localediff ./locales`.
+
+## What it checks
+
+| Check | Meaning |
+|-------|---------|
+| **missing** | a key in the base that the target never translated |
+| **plural** | a pluralized key (`key_one`, `key_other`, …) missing a CLDR form the **target language** requires |
+| **empty** | a key present in the target whose value is a blank string |
+| **extra** | a key in the target the base no longer has |
+
+Nested objects are flattened to dot-paths (`auth.errors.locked`); arrays are
+indexed (`steps.0`). Plural keys use the i18next suffix convention
+(`_zero`, `_one`, `_two`, `_few`, `_many`, `_other`). Unknown languages fall back
+to parity with the base, so you never get a confidently-wrong result.
+
+## Options
+
+```
+--base <file|lang>    base/source locale (a file, or a lang stem in dir mode)
+--check <files...>    one or more target locales to compare against the base
+--dir <dir>           scan a directory of *.json locales
+--lang <code>         force the target language for plural rules
+--format text|json    output format (default: text)
+--ignore-missing      don't report missing keys
+--ignore-extra        don't report extra keys
+--ignore-plural       don't report plural gaps
+--ignore-empty        don't report empty values
+-v, --version
+-h, --help
+```
+
+## In CI
+
+`localediff` exits non-zero when anything has drifted:
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | every checked file is in sync |
+| `1` | one or more files have drift |
+| `2` | error (file not found, invalid JSON, bad arguments) |
+
+## Also available for Node
+
+```bash
+npx localediff ./locales
+```
+
+Same checks, same flags, same exit codes — [localediff on npm](https://github.com/jjdoor/localediff).
+
+## Scope
+
+JSON locale files only (the common case). YAML/`.properties`/gettext are not
+supported — parsing them would mean pulling in a dependency, and zero-dep is the
+point. Convert to JSON, or open an issue to discuss.
+
+## License
+
+MIT

localediff-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "localediff"
+version = "0.1.0"
+description = "Find drift between i18n locale files — missing keys, CLDR-aware plural gaps, empty values. Framework-agnostic, zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["i18n", "l10n", "locale", "translation", "missing-translations", "drift", "diff", "i18next", "cli", "ci", "pluralization"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Internationalization",
+    "Topic :: Software Development :: Localization",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/localediff-py"
+Repository = "https://github.com/jjdoor/localediff-py"
+Issues = "https://github.com/jjdoor/localediff-py/issues"
+
+[project.scripts]
+localediff = "localediff.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

localediff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

localediff-0.1.0/src/localediff/__init__.py

@@ -0,0 +1,6 @@
+"""localediff — find drift between i18n locale files. Framework-agnostic, zero deps."""
+
+from .core import compare, flatten, normalize_lang, required_categories
+
+__version__ = "0.1.0"
+__all__ = ["compare", "flatten", "normalize_lang", "required_categories"]

localediff-0.1.0/src/localediff/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

localediff-0.1.0/src/localediff/cli.py

@@ -0,0 +1,200 @@
+"""localediff command-line interface."""
+
+import json
+import os
+import re
+import sys
+
+from . import core, report
+
+VERSION = "0.1.0"
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+COLORS = {
+    "red": lambda s: _c("31", s),
+    "green": lambda s: _c("32", s),
+    "yellow": lambda s: _c("33", s),
+    "cyan": lambda s: _c("36", s),
+    "dim": lambda s: _c("2", s),
+    "bold": lambda s: _c("1", s),
+}
+
+
+def red(s):
+    return COLORS["red"](s)
+
+
+HELP = f"""{COLORS['bold']('localediff')} — find drift between i18n locale files. Framework-agnostic, zero deps.
+
+{COLORS['bold']('Usage')}
+  localediff --base en.json --check fr.json zh.json   compare files explicitly
+  localediff ./locales                                scan a dir (base: en.json)
+  localediff ./locales --base de                      scan a dir, base de.json
+  localediff en.json fr.json zh.json                  first file is the base
+
+{COLORS['bold']('What it finds')}
+  missing  key in the base, never translated in the target
+  plural   pluralized key missing a CLDR form the target language needs
+  empty    key present in the target but its value is blank
+  extra    key in the target the base no longer has
+
+{COLORS['bold']('Options')}
+  --base <file|lang>    base/source locale (a file, or a lang stem in dir mode)
+  --check <files...>    one or more target locales to compare against the base
+  --dir <dir>           scan a directory of *.json locales
+  --lang <code>         force the target language for plural rules (else inferred
+                        from each file name, e.g. fr.json -> fr)
+  --format text|json    output format (default: text)
+  --ignore-missing      don't report missing keys
+  --ignore-extra        don't report extra keys
+  --ignore-plural       don't report plural gaps
+  --ignore-empty        don't report empty values
+  -v, --version
+  -h, --help
+
+{COLORS['bold']('Exit')}  0 in sync · 1 drift found · 2 error
+"""
+
+
+def fail(msg):
+    sys.stderr.write(red(f"localediff: {msg}\n"))
+    sys.exit(2)
+
+
+def read_json(file):
+    try:
+        with open(file, "r", encoding="utf-8") as fh:
+            text = fh.read()
+    except FileNotFoundError:
+        return fail(f"cannot read {file}: no such file")
+    except OSError as e:
+        return fail(f"cannot read {file}: {e}")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        return fail(f"invalid JSON in {file}: {e}")
+
+
+def flag(args, name):
+    """Value after --name, or None."""
+    if name in args:
+        i = args.index(name)
+        if i + 1 < len(args):
+            return args[i + 1]
+    return None
+
+
+def has(args, name):
+    return name in args
+
+
+def collect_check(args):
+    """Values after --check up to the next --flag."""
+    if "--check" not in args:
+        return []
+    i = args.index("--check")
+    out = []
+    j = i + 1
+    while j < len(args) and not args[j].startswith("--"):
+        out.append(args[j])
+        j += 1
+    return out
+
+
+def lang_stem(file):
+    return re.sub(r"\.json$", "", os.path.basename(file), flags=re.IGNORECASE)
+
+
+def resolve_inputs(args):
+    opts = {
+        "ignoreMissing": has(args, "--ignore-missing"),
+        "ignoreExtra": has(args, "--ignore-extra"),
+        "ignorePlural": has(args, "--ignore-plural"),
+        "ignoreEmpty": has(args, "--ignore-empty"),
+    }
+    fmt = flag(args, "--format") or "text"
+    if fmt not in ("text", "json"):
+        fail("--format must be text or json")
+    forced_lang = flag(args, "--lang")
+
+    consumed = set()
+    for f in ("--base", "--format", "--dir", "--lang"):
+        if f in args:
+            i = args.index(f)
+            consumed.add(i)
+            consumed.add(i + 1)
+    if "--check" in args:
+        ci = args.index("--check")
+        consumed.add(ci)
+        j = ci + 1
+        while j < len(args) and not args[j].startswith("--"):
+            consumed.add(j)
+            j += 1
+    positionals = [a for i, a in enumerate(args) if not a.startswith("--") and i not in consumed]
+
+    base_arg = flag(args, "--base")
+    check_args = collect_check(args)
+    dir_ = flag(args, "--dir")
+    if not dir_ and len(positionals) == 1 and os.path.isdir(positionals[0]):
+        dir_ = positionals[0]
+
+    if dir_:
+        if not os.path.isdir(dir_):
+            fail(f"not a directory: {dir_}")
+        jsons = sorted(f for f in os.listdir(dir_) if re.search(r"\.json$", f, re.IGNORECASE))
+        if not jsons:
+            fail(f"no .json locale files in {dir_}")
+        base_lang = lang_stem(base_arg) if base_arg else "en"
+        base_name = next((f for f in jsons if lang_stem(f) == base_lang), None)
+        if not base_name:
+            fail(f'base locale "{base_lang}.json" not found in {dir_} (have: {", ".join(jsons)})')
+        base_file = os.path.join(dir_, base_name)
+        check_files = [os.path.join(dir_, f) for f in jsons if f != base_name]
+        if not check_files:
+            fail(f"only the base locale is present in {dir_}; nothing to compare")
+    elif base_arg and check_args:
+        base_file = base_arg
+        check_files = check_args
+    elif len(positionals) >= 2:
+        base_file = positionals[0]
+        check_files = positionals[1:]
+    else:
+        fail("nothing to compare. Try:  localediff --base en.json --check fr.json   or   localediff ./locales")
+    return base_file, check_files, opts, fmt, forced_lang
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else argv
+    if not args or args[0] in ("-h", "--help"):
+        sys.stdout.write(HELP)
+        return 0
+    if args[0] in ("-v", "--version"):
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    base_file, check_files, opts, fmt, forced_lang = resolve_inputs(args)
+    base = read_json(base_file)
+
+    results = []
+    for file in check_files:
+        lang = forced_lang or core.normalize_lang(lang_stem(file))
+        rep = core.compare(base, read_json(file), {**opts, "lang": lang})
+        results.append({"file": file, "base": base_file, "lang": lang, "report": rep})
+
+    if fmt == "json":
+        sys.stdout.write(report.format_json(results) + "\n")
+    else:
+        sys.stdout.write(report.format_text(results, COLORS if _COLOR else None) + "\n")
+
+    return 1 if any(not r["report"]["inSync"] for r in results) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

localediff-0.1.0/src/localediff/core.py

@@ -0,0 +1,212 @@
+"""localediff core — pure locale-comparison logic. No fs, no clock, no network.
+
+Given a base locale object (the source of truth, e.g. en.json) and a target
+locale object (e.g. fr.json), find where they have drifted apart:
+
+  - missing keys   the base has a key the target never translated
+  - extra keys     the target still has a key the base has dropped
+  - plural gaps    the target is missing a CLDR plural form its own language
+                   requires (i18next ``_one`` / ``_other`` / ``_few`` ... suffixes)
+  - empty values   the key exists in the target but its string is blank
+
+Comparison is structural and framework-agnostic: nested objects/arrays are
+flattened to dot-paths, so it works for next-intl, react-intl, i18next,
+vue-i18n, or any plain JSON message catalog. Behavior mirrors the Node package
+of the same name exactly, so both produce identical reports.
+
+The plural check is CLDR-aware on purpose. A naive "the target must have every
+form the base has" rule false-positives on languages with fewer plural
+categories than English — Chinese/Japanese/Korean only ever need ``other``, so
+an ``items_other``-only zh.json is *correct*, while the same shape in fr.json is
+a real bug. We resolve the required categories from the target's language.
+"""
+
+import re
+
+PLURAL_CATEGORIES = ["zero", "one", "two", "few", "many", "other"]
+_PLURAL_RE = re.compile(r"^(.+)_(zero|one|two|few|many|other)$")
+
+# CLDR cardinal plural categories needed for everyday integer counts, keyed by
+# language. Conservative on purpose — only languages we're confident about are
+# listed; anything else falls back to parity with the base (see
+# required_categories). Decimal-only categories (e.g. Romance "many" for compact
+# millions) are deliberately omitted to avoid noisy false positives.
+LANG_PLURALS = {
+    # no count distinction — `other` is the only form
+    "zh": ["other"], "ja": ["other"], "ko": ["other"], "vi": ["other"],
+    "th": ["other"], "id": ["other"], "ms": ["other"], "lo": ["other"],
+    "km": ["other"], "my": ["other"], "yo": ["other"],
+    # one / other (the large majority)
+    "en": ["one", "other"], "de": ["one", "other"], "nl": ["one", "other"],
+    "sv": ["one", "other"], "da": ["one", "other"], "nb": ["one", "other"],
+    "nn": ["one", "other"], "no": ["one", "other"], "fi": ["one", "other"],
+    "es": ["one", "other"], "it": ["one", "other"], "pt": ["one", "other"],
+    "fr": ["one", "other"], "ca": ["one", "other"], "gl": ["one", "other"],
+    "el": ["one", "other"], "hu": ["one", "other"], "tr": ["one", "other"],
+    "fa": ["one", "other"], "hi": ["one", "other"], "bg": ["one", "other"],
+    "et": ["one", "other"], "eu": ["one", "other"], "af": ["one", "other"],
+    # Slavic & friends: one / few / many / other
+    "ru": ["one", "few", "many", "other"], "uk": ["one", "few", "many", "other"],
+    "pl": ["one", "few", "many", "other"], "be": ["one", "few", "many", "other"],
+    "lt": ["one", "few", "many", "other"],
+    # one / few / other
+    "cs": ["one", "few", "other"], "sk": ["one", "few", "other"],
+    "hr": ["one", "few", "other"], "sr": ["one", "few", "other"],
+    "ro": ["one", "few", "other"],
+    # smaller sets
+    "lv": ["zero", "one", "other"], "sl": ["one", "two", "few", "other"],
+    # all six
+    "ar": ["zero", "one", "two", "few", "many", "other"],
+    "cy": ["zero", "one", "two", "few", "many", "other"],
+}
+
+
+def normalize_lang(tag) -> str:
+    """Normalize a locale tag to its base language code.
+
+    "zh-Hans-CN" -> "zh", "pt_BR" -> "pt", "EN" -> "en".
+    """
+    return re.split(r"[-_]", str(tag or "").lower())[0]
+
+
+def flatten(obj):
+    """Flatten a nested object/array into ordered ``(path, value)`` leaf tuples.
+
+    ``{"a": {"b": 1}, "c": [2, 3]}`` becomes
+    ``[("a.b", 1), ("c.0", 2), ("c.1", 3)]``, in document order (depth-first).
+    Empty dicts/lists are kept as leaves so their key still participates.
+    """
+    out = []
+    _walk(obj, "", out)
+    return out
+
+
+def _walk(value, prefix, out):
+    if isinstance(value, dict):
+        if not value:
+            out.append((prefix, value))
+            return
+        for k, child in value.items():
+            _walk(child, k if prefix == "" else f"{prefix}.{k}", out)
+    elif isinstance(value, list):
+        if not value:
+            out.append((prefix, value))
+            return
+        for i, child in enumerate(value):
+            _walk(child, str(i) if prefix == "" else f"{prefix}.{i}", out)
+    else:
+        out.append((prefix, value))
+
+
+def split_plural(path):
+    """If ``path`` ends with a CLDR plural suffix, return ``(stem, category)``.
+
+    "items_one" -> ("items", "one"). Otherwise return None.
+    """
+    m = _PLURAL_RE.match(path)
+    return (m.group(1), m.group(2)) if m else None
+
+
+def plural_groups(entries):
+    """Group plural-suffixed leaf paths by stem.
+
+    Only stems whose category set includes ``other`` (the form i18next always
+    requires) count as real plural groups — this keeps ordinary keys like
+    ``step_one`` from being mistaken for a plural. Returns ``dict[stem, set]`` in
+    first-seen order.
+    """
+    groups = {}
+    for path, _value in entries:
+        sp = split_plural(path)
+        if not sp:
+            continue
+        stem, cat = sp
+        groups.setdefault(stem, set()).add(cat)
+    for stem in [s for s, cats in groups.items() if "other" not in cats]:
+        del groups[stem]
+    return groups
+
+
+def _order_cats(cat_set):
+    return [c for c in PLURAL_CATEGORIES if c in cat_set]
+
+
+def required_categories(lang, base_cats):
+    """The plural categories a target file should define for a count-based key.
+
+    Uses the CLDR table for known languages; falls back to parity with the
+    base's own categories when the language is unknown (the right default for
+    the common en->X case).
+    """
+    table = LANG_PLURALS.get(lang)
+    return list(table) if table else _order_cats(base_cats)
+
+
+def _is_blank(value):
+    return isinstance(value, str) and value.strip() == ""
+
+
+def compare(base, target, opts=None):
+    """Compare a target locale against the base; return a structured drift report.
+
+    ``opts`` may carry ``lang`` plus ``ignoreMissing`` / ``ignoreExtra`` /
+    ``ignorePlural`` / ``ignoreEmpty`` booleans.
+    """
+    opts = opts or {}
+    base_entries = flatten(base)
+    target_entries = flatten(target)
+
+    base_plurals = plural_groups(base_entries)
+    target_plurals = plural_groups(target_entries)
+    plural_stems = set(base_plurals.keys())
+
+    def in_base_plural_stem(path):
+        sp = split_plural(path)
+        return sp is not None and sp[0] in plural_stems
+
+    base_plain = [(p, v) for (p, v) in base_entries if not in_base_plural_stem(p)]
+    target_plain = [(p, v) for (p, v) in target_entries if not in_base_plural_stem(p)]
+
+    target_plain_paths = {p for (p, _v) in target_plain}
+    base_plain_paths = {p for (p, _v) in base_plain}
+    base_value = {p: v for (p, v) in base_entries}
+
+    missing = [p for (p, _v) in base_plain if p not in target_plain_paths]
+    extra = [p for (p, _v) in target_plain if p not in base_plain_paths]
+
+    lang = normalize_lang(opts.get("lang"))
+    plural = []
+    for stem, base_cats in base_plurals.items():
+        t_cats = target_plurals.get(stem, set())
+        required = required_categories(lang, base_cats)
+        missing_cats = [c for c in required if c not in t_cats]
+        if missing_cats:
+            plural.append({
+                "stem": stem,
+                "required": required,
+                "have": _order_cats(t_cats),
+                "missing": missing_cats,
+            })
+
+    empty = []
+    for path, value in target_entries:
+        bv = base_value.get(path)
+        if _is_blank(value) and isinstance(bv, str) and not _is_blank(bv):
+            empty.append(path)
+
+    report = {
+        "missing": [] if opts.get("ignoreMissing") else missing,
+        "extra": [] if opts.get("ignoreExtra") else extra,
+        "plural": [] if opts.get("ignorePlural") else plural,
+        "empty": [] if opts.get("ignoreEmpty") else empty,
+    }
+    report["counts"] = {
+        "missing": len(report["missing"]),
+        "extra": len(report["extra"]),
+        "plural": len(report["plural"]),
+        "empty": len(report["empty"]),
+    }
+    report["inSync"] = all(
+        report["counts"][k] == 0 for k in ("missing", "extra", "plural", "empty")
+    )
+    return report

localediff-0.1.0/src/localediff/report.py

@@ -0,0 +1,90 @@
+"""Formatting for localediff reports. Pure: data + a color palette -> string."""
+
+import json
+
+
+def _identity(s):
+    return s
+
+
+_PLAIN = {
+    "red": _identity, "green": _identity, "yellow": _identity,
+    "cyan": _identity, "dim": _identity, "bold": _identity,
+}
+
+
+def format_text(results, c=None):
+    """Render per-file results as human-readable text.
+
+    ``results`` is a list of ``{"file", "report", ...}`` dicts. ``c`` is an
+    optional color palette (a dict of name -> callable); defaults to no color.
+    """
+    c = c or _PLAIN
+    lines = []
+    drift_files = 0
+    totals = {"missing": 0, "extra": 0, "plural": 0, "empty": 0}
+
+    for r in results:
+        rep = r["report"]
+        file = r["file"]
+        if rep["inSync"]:
+            lines.append(f"{c['green']('✓')} {c['bold'](file)} {c['dim']('— in sync')}")
+            continue
+        drift_files += 1
+        lines.append(f"{c['red']('✗')} {c['bold'](file)}")
+        if rep["missing"]:
+            lines.append(f"  {c['yellow']('missing')} ({len(rep['missing'])}): "
+                         f"{', '.join(rep['missing'])}")
+        for p in rep["plural"]:
+            if p["have"]:
+                detail = f"has {{{','.join(p['have'])}}}, missing {{{','.join(p['missing'])}}}"
+            else:
+                detail = f"untranslated, needs {{{','.join(p['missing'])}}}"
+            lines.append(f"  {c['cyan']('plural')}  {p['stem']} — {detail}")
+        if rep["empty"]:
+            lines.append(f"  {c['dim']('empty')}   ({len(rep['empty'])}): "
+                         f"{', '.join(rep['empty'])}")
+        if rep["extra"]:
+            lines.append(f"  {c['dim']('extra')}   ({len(rep['extra'])}): "
+                         f"{', '.join(rep['extra'])}")
+        lines.append("")
+        for k in totals:
+            totals[k] += rep["counts"][k]
+
+    if drift_files == 0:
+        summary = c["green"](f"✓ all {len(results)} file(s) in sync")
+    else:
+        summary = (
+            c["red"](f"✗ {drift_files} of {len(results)} file(s) drifted")
+            + c["dim"](f" — {totals['missing']} missing, {totals['plural']} plural gap(s), "
+                       f"{totals['empty']} empty, {totals['extra']} extra")
+        )
+    lines.append(summary)
+    return "\n".join(lines)
+
+
+def format_json(results):
+    """Render results as machine-readable JSON for CI consumption."""
+    files = []
+    for r in results:
+        rep = r["report"]
+        files.append({
+            "file": r["file"],
+            "base": r["base"],
+            "lang": r.get("lang"),
+            "inSync": rep["inSync"],
+            "missing": rep["missing"],
+            "plural": rep["plural"],
+            "empty": rep["empty"],
+            "extra": rep["extra"],
+            "counts": rep["counts"],
+        })
+    drifted = sum(1 for f in files if not f["inSync"])
+    out = {
+        "base": results[0]["base"] if results else None,
+        "checked": len(files),
+        "drifted": drifted,
+        "inSync": drifted == 0,
+        "files": files,
+    }
+    return json.dumps(out, indent=2, ensure_ascii=False)

localediff-0.1.0/src/localediff.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: localediff
+Version: 0.1.0
+Summary: Find drift between i18n locale files — missing keys, CLDR-aware plural gaps, empty values. Framework-agnostic, zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/localediff-py
+Project-URL: Repository, https://github.com/jjdoor/localediff-py
+Project-URL: Issues, https://github.com/jjdoor/localediff-py/issues
+Keywords: i18n,l10n,locale,translation,missing-translations,drift,diff,i18next,cli,ci,pluralization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# localediff
+
+**Find drift between your i18n locale files — before your users do.** You add a
+string to `en.json`, ship it, and three weeks later notice `fr.json` and
+`zh.json` were never updated. `localediff` catches that in CI: missing keys,
+plural forms a language actually needs, and keys that exist but were left blank.
+Framework-agnostic, **zero dependencies**.
+
+```bash
+pip install localediff
+localediff ./locales
+```
+
+```
+✗ fr.json
+  missing (1): auth.errors.locked
+  plural  cart.items — has {other}, missing {one}
+  empty   (1): footer.copyright
+  extra   (1): legacy.banner
+
+✓ zh.json — in sync
+
+✗ 1 of 2 file(s) drifted — 1 missing, 1 plural gap(s), 1 empty, 1 extra
+```
+
+## Why another i18n tool
+
+Most existing tools are tied to one framework, need an account, or are heavy
+AST-based linters. `localediff` just reads JSON. It compares **structure**, so it
+works for next-intl, react-intl, i18next, vue-i18n, Django/Flask JSON catalogs,
+or any plain message file — and it ships for **both PyPI and npm** with identical
+behavior.
+
+### It understands plurals per language
+
+This is the part naive "diff two JSON files" scripts get wrong. English has two
+plural forms (`one`, `other`); Chinese has one (`other`); Russian has four
+(`one`, `few`, `many`, `other`). A file with only `items_other` is **correct for
+Chinese** but **broken for French**. `localediff` resolves the required CLDR
+categories from each target's language, so it flags the real bug without crying
+wolf on `zh.json`.
+
+```bash
+# en base: items_one + items_other
+zh.json  →  items_other only   →  ✓ in sync   (Chinese needs only `other`)
+fr.json  →  items_other only   →  ✗ missing {one}
+ru.json  →  items_one + _other →  ✗ missing {few, many}
+```
+
+## Usage
+
+```bash
+# Scan a folder. The base defaults to en.json; everything else is checked.
+localediff ./locales
+
+# Pick a different base language in the folder.
+localediff ./locales --base de
+
+# Compare specific files explicitly.
+localediff --base en.json --check fr.json zh.json
+
+# Shorthand: first file is the base.
+localediff en.json fr.json zh.json
+
+# Machine-readable output for CI gates.
+localediff ./locales --format json
+```
+
+You can also run it as a module: `python -m localediff ./locales`.
+
+## What it checks
+
+| Check | Meaning |
+|-------|---------|
+| **missing** | a key in the base that the target never translated |
+| **plural** | a pluralized key (`key_one`, `key_other`, …) missing a CLDR form the **target language** requires |
+| **empty** | a key present in the target whose value is a blank string |
+| **extra** | a key in the target the base no longer has |
+
+Nested objects are flattened to dot-paths (`auth.errors.locked`); arrays are
+indexed (`steps.0`). Plural keys use the i18next suffix convention
+(`_zero`, `_one`, `_two`, `_few`, `_many`, `_other`). Unknown languages fall back
+to parity with the base, so you never get a confidently-wrong result.
+
+## Options
+
+```
+--base <file|lang>    base/source locale (a file, or a lang stem in dir mode)
+--check <files...>    one or more target locales to compare against the base
+--dir <dir>           scan a directory of *.json locales
+--lang <code>         force the target language for plural rules
+--format text|json    output format (default: text)
+--ignore-missing      don't report missing keys
+--ignore-extra        don't report extra keys
+--ignore-plural       don't report plural gaps
+--ignore-empty        don't report empty values
+-v, --version
+-h, --help
+```
+
+## In CI
+
+`localediff` exits non-zero when anything has drifted:
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | every checked file is in sync |
+| `1` | one or more files have drift |
+| `2` | error (file not found, invalid JSON, bad arguments) |
+
+## Also available for Node
+
+```bash
+npx localediff ./locales
+```
+
+Same checks, same flags, same exit codes — [localediff on npm](https://github.com/jjdoor/localediff).
+
+## Scope
+
+JSON locale files only (the common case). YAML/`.properties`/gettext are not
+supported — parsing them would mean pulling in a dependency, and zero-dep is the
+point. Convert to JSON, or open an issue to discuss.
+
+## License
+
+MIT

localediff-0.1.0/src/localediff.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/localediff/__init__.py
+src/localediff/__main__.py
+src/localediff/cli.py
+src/localediff/core.py
+src/localediff/report.py
+src/localediff.egg-info/PKG-INFO
+src/localediff.egg-info/SOURCES.txt
+src/localediff.egg-info/dependency_links.txt
+src/localediff.egg-info/entry_points.txt
+src/localediff.egg-info/top_level.txt
+tests/test_core.py
+tests/test_report.py

localediff-0.1.0/src/localediff.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

localediff-0.1.0/src/localediff.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+localediff = localediff.cli:main

localediff-0.1.0/src/localediff.egg-info/top_level.txt

@@ -0,0 +1 @@
+localediff

localediff-0.1.0/tests/test_core.py

@@ -0,0 +1,113 @@
+from localediff.core import (
+    compare, flatten, normalize_lang, plural_groups, required_categories, split_plural,
+)
+
+
+def test_flatten_dot_paths_in_document_order():
+    entries = flatten({"a": {"b": 1, "c": 2}, "d": 3})
+    assert entries == [("a.b", 1), ("a.c", 2), ("d", 3)]
+
+
+def test_flatten_indexes_arrays_and_keeps_empty_containers():
+    entries = flatten({"list": ["x", "y"], "blank": {}, "none": []})
+    assert [p for p, _ in entries] == ["list.0", "list.1", "blank", "none"]
+
+
+def test_split_plural_recognizes_cldr_suffixes_only():
+    assert split_plural("items_one") == ("items", "one")
+    assert split_plural("a.b.count_many") == ("a.b.count", "many")
+    assert split_plural("items") is None
+    assert split_plural("step_two_factor") is None
+
+
+def test_plural_groups_keeps_only_groups_with_other():
+    entries = flatten({
+        "items_one": "a", "items_other": "b",   # real plural
+        "step_one": "x", "step_two": "y",       # NOT a plural (no `other`)
+    })
+    groups = plural_groups(entries)
+    assert list(groups.keys()) == ["items"]
+    assert groups["items"] == {"one", "other"}
+
+
+def test_normalize_lang_strips_region_script_subtags():
+    assert normalize_lang("zh-Hans-CN") == "zh"
+    assert normalize_lang("pt_BR") == "pt"
+    assert normalize_lang("FR") == "fr"
+    assert normalize_lang("") == ""
+    assert normalize_lang(None) == ""
+
+
+def test_required_categories_table_then_parity_fallback():
+    assert required_categories("zh", {"one", "other"}) == ["other"]
+    assert required_categories("ru", {"one", "other"}) == ["one", "few", "many", "other"]
+    assert required_categories("xx", {"one", "other"}) == ["one", "other"]
+
+
+def test_compare_missing_and_extra_plain_keys():
+    base = {"a": "1", "b": "2", "nested": {"c": "3"}}
+    target = {"a": "uno", "nested": {"c": "tres", "d": "cuatro"}}
+    r = compare(base, target, {"lang": "es"})
+    assert r["missing"] == ["b"]
+    assert r["extra"] == ["nested.d"]
+    assert r["inSync"] is False
+
+
+def test_compare_empty_values_only_when_base_has_text():
+    base = {"a": "hello", "b": "world", "c": ""}
+    target = {"a": "", "b": "   ", "c": ""}
+    r = compare(base, target, {"lang": "de"})
+    assert r["empty"] == ["a", "b"]
+
+
+def test_compare_plural_gap_respects_target_language():
+    base = {"items_one": "{{count}} item", "items_other": "{{count}} items"}
+
+    # Chinese only needs `other` — an `_other`-only file is CORRECT.
+    zh = compare(base, {"items_other": "件"}, {"lang": "zh"})
+    assert zh["plural"] == []
+    assert zh["inSync"] is True
+
+    # French needs one+other — the same shape IS a bug.
+    fr = compare(base, {"items_other": "articles"}, {"lang": "fr"})
+    assert fr["plural"] == [
+        {"stem": "items", "required": ["one", "other"], "have": ["other"], "missing": ["one"]}
+    ]
+
+    # Russian needs four forms — flags few+many even though the base lacks them.
+    ru = compare(base, {"items_one": "товар", "items_other": "товара"}, {"lang": "ru"})
+    assert ru["plural"][0]["missing"] == ["few", "many"]
+
+
+def test_compare_plural_members_not_double_reported_as_missing():
+    base = {"items_one": "a", "items_other": "b"}
+    r = compare(base, {}, {"lang": "fr"})
+    assert r["missing"] == []
+    assert len(r["plural"]) == 1
+    assert r["plural"][0]["have"] == []
+
+
+def test_compare_ordinary_one_two_keys_are_plain_keys():
+    base = {"step_one": "First", "step_two": "Second"}
+    target = {"step_one": "Premier"}
+    r = compare(base, target, {"lang": "fr"})
+    assert r["plural"] == []
+    assert r["missing"] == ["step_two"]
+
+
+def test_compare_ignore_flags_reach_in_sync():
+    base = {"a": "1", "b": "2"}
+    target = {"a": "uno", "c": "tres"}
+    assert compare(base, target, {"lang": "es"})["inSync"] is False
+    r = compare(base, target, {"lang": "es", "ignoreMissing": True, "ignoreExtra": True})
+    assert r["missing"] == []
+    assert r["extra"] == []
+    assert r["inSync"] is True
+
+
+def test_compare_identical_locales_in_sync():
+    base = {"a": "1", "nested": {"b": "2"}, "items_one": "x", "items_other": "y"}
+    import copy
+    r = compare(base, copy.deepcopy(base), {"lang": "en"})
+    assert r["inSync"] is True
+    assert r["counts"] == {"missing": 0, "extra": 0, "plural": 0, "empty": 0}

localediff-0.1.0/tests/test_report.py

@@ -0,0 +1,46 @@
+import json
+
+from localediff.core import compare
+from localediff.report import format_json, format_text
+
+BASE = {"a": "1", "b": "2", "items_one": "x", "items_other": "y", "footer": "hi"}
+
+
+def build_results():
+    fr = compare(BASE, {"a": "uno", "items_other": "y", "footer": "", "legacy": "old"}, {"lang": "fr"})
+    zh = compare(BASE, {"a": "1", "b": "2", "items_other": "y", "footer": "hi"}, {"lang": "zh"})
+    return [
+        {"file": "fr.json", "base": "en.json", "lang": "fr", "report": fr},
+        {"file": "zh.json", "base": "en.json", "lang": "zh", "report": zh},
+    ]
+
+
+def test_format_text_labels_each_category_and_in_sync_file():
+    out = format_text(build_results())
+    assert "✗ fr.json" in out
+    assert "missing (1): b" in out
+    assert "plural  items — has {other}, missing {one}" in out
+    assert "empty   (1): footer" in out
+    assert "extra   (1): legacy" in out
+    assert "✓ zh.json" in out
+
+
+def test_format_text_summary_counts_drifted_files():
+    out = format_text(build_results())
+    assert "✗ 1 of 2 file(s) drifted" in out
+
+
+def test_format_text_all_in_sync():
+    ok = compare(BASE, BASE, {"lang": "en"})
+    out = format_text([{"file": "en2.json", "base": "en.json", "report": ok}])
+    assert "✓ all 1 file(s) in sync" in out
+
+
+def test_format_json_valid_with_detail_and_totals():
+    parsed = json.loads(format_json(build_results()))
+    assert parsed["checked"] == 2
+    assert parsed["drifted"] == 1
+    assert parsed["inSync"] is False
+    assert parsed["files"][0]["file"] == "fr.json"
+    assert parsed["files"][0]["counts"]["missing"] == 1
+    assert parsed["files"][1]["inSync"] is True