localizer-py 0.5.0__tar.gz

localizer_py-0.5.0/.gitignore

@@ -0,0 +1,13 @@
+/bin/
+*.test
+*.out
+coverage.txt
+.DS_Store
+python/localizer/_version.py
+python/dist/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+python/**/uv.lock
+site/public/AGENTS.md

localizer_py-0.5.0/LICENSE

@@ -0,0 +1,35 @@
+University of Illinois/NCSA Open Source License
+
+Copyright (c) 2026 Snizyx Software LLC. All rights reserved.
+
+Developed by: Localizer
+              Snizyx Software LLC
+              https://locale.dev
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files
+(the "Software"), to deal with 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:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimers.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimers in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the names of Snizyx Software LLC, Localizer nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this Software without specific prior written permission.
+
+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
+CONTRIBUTORS 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 WITH
+THE SOFTWARE.
+

localizer_py-0.5.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: localizer-py
+Version: 0.5.0
+Import-Name: localizer
+Summary: Render your Typer, Click or argparse CLI in the user's language with Localizer catalogs.
+Project-URL: Homepage, https://locale.dev/
+Project-URL: Documentation, https://locale.dev/reference/runtime/
+Project-URL: Source, https://github.com/DABH/localizer
+Project-URL: Changelog, https://github.com/DABH/localizer/releases
+Author: Snizyx Software LLC
+License-Expression: NCSA
+License-File: LICENSE
+Keywords: argparse,cli,click,i18n,localization,typer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# localizer-py
+
+Render a Typer, Click or argparse CLI's own strings — help text, option descriptions, messages,
+errors, prompts — in the user's language. Translations come from JSON catalogs committed to your
+repository and shipped inside your package; nothing is downloaded or executed at runtime, and a CLI
+without a matching catalog behaves exactly as before.
+
+The catalogs are written by [Localizer](https://locale.dev/): install the GitHub App or add the
+GitHub Action to your repository and it keeps a pull request up to date with translations of every
+string it finds in your code. This package is the runtime half — the part that runs on your users'
+machines.
+
+```sh
+pip install localizer-py   # not "localizer", which is an unrelated project
+```
+
+Python 3.10 or newer, no dependencies. Works with Click 8.1+, Typer 0.17+ (including Typer's
+bundled Click) and the standard library's argparse.
+
+## One line
+
+Call `localize` after every command and option is registered, right before the app runs:
+
+```python
+import localizer
+
+# Typer
+app = typer.Typer()
+...
+if __name__ == "__main__":
+    localizer.localize(app, "yourcli.locales")
+    app()
+
+# Click
+@click.group()
+def cli(): ...
+
+def main():
+    localizer.localize(cli, "yourcli.locales")
+    cli()
+
+# argparse
+parser = argparse.ArgumentParser(prog="yourcli")
+...
+localizer.localize(parser, "yourcli.locales")
+args = parser.parse_args()
+```
+
+`"yourcli.locales"` names the package holding your catalogs (`yourcli/locales/ja.json`, …); a
+directory path or an `importlib.resources` Traversable works too. If your CLI builds its command
+tree in a factory, call `localize` where the finished app object is handed out — translation happens
+when help and errors are rendered, so commands registered later (plugins, lazy groups) are covered.
+
+What is translated: your help text and option descriptions, the framework's own messages (`Usage:`,
+`Show this message and exit.`, `Missing argument 'NAME'.`, `Aborted!`, prompts, argparse's `error:`
+lines — built-in catalogs for these ship in this package), the messages of exceptions your CLI
+raises, and whatever your program passes through the helpers below. Nothing else changes: command and
+option names, values, JSON/YAML output and logs stay as they are.
+
+## Your own messages
+
+```python
+from localizer import t, tf, error
+
+print(t("Nothing to do."))                          # exact lookup, or the English text
+print(tf("Added task {n}: {title!r}", n=3, title=s))  # translated format string, then .format()
+console.print(t(f"Deleted {count} files"))          # formatted text is matched against the catalog
+raise click.ClickException(error(exc))              # an exception's message, for display
+```
+
+`t` on a format string looks the template up exactly (call it before formatting, or use `tf`); on
+finished text it reverse-matches the catalog's templates, so `f"Deleted {count} files"` finds
+`Deleted {count} files` and keeps the number. `localizer.translate(text, localizer.Mode.ERROR)`
+does the same for chokepoints that receive already-formatted messages. Every helper returns its input
+unchanged when there is no translation and never raises.
+
+## Catalogs
+
+One file per language, named by BCP 47 tag, keyed by the exact English source string:
+
+```json
+{
+  "version": 1,
+  "language": "ja",
+  "format": "python",
+  "messages": {
+    "Add a task.": "タスクを追加します。",
+    "Added task {n}: {title!r}": "タスク {n} を追加しました: {title!r}"
+  }
+}
+```
+
+Localizer generates and maintains these; you review them like any other pull request. Make sure the
+JSON files are packaged: hatchling, poetry, flit, pdm and uv include them automatically, setuptools
+needs `[tool.setuptools.package-data] yourcli = ["locales/*.json"]`.
+
+## Language selection
+
+`LOCALIZER_LANG`, then `LC_ALL`, `LC_MESSAGES`, `LANG` (and `LANGUAGE`), then the operating system's
+preferred languages on macOS and Windows; the best available catalog wins, English is the default.
+`localize(app, ..., env_var="YOURCLI_LANG")` adds an application-specific override checked first;
+`language="de"` forces a language. Setting the variable to `off` keeps a CLI in English;
+`LOCALIZER_LANG=qps` pseudo-localizes every translatable string (`⟦Ûšáĝé:⟧`) so you can see what is
+covered without a catalog. `LOCALIZER_DEBUG=1` reports untranslated strings and swallowed hook errors
+on stderr; `LOCALIZER_DUMP=path.json` writes the help tree with a translated/untranslated flag per
+entry.
+
+Pin your tests to English so snapshots don't depend on the machine's locale:
+
+```python
+# conftest.py
+import os
+
+def pytest_configure(config):
+    os.environ.setdefault("LOCALIZER_LANG", "en")
+```
+
+## More
+
+- Documentation: https://locale.dev/ — [runtime reference](https://locale.dev/reference/runtime/),
+  [integration guide](https://locale.dev/guides/integration/)
+- Coding agents: point yours at https://locale.dev/AGENTS.md to integrate Localizer into a CLI
+- Source: https://github.com/DABH/localizer (`python/`); license: NCSA

localizer_py-0.5.0/README.md

@@ -0,0 +1,123 @@
+# localizer-py
+
+Render a Typer, Click or argparse CLI's own strings — help text, option descriptions, messages,
+errors, prompts — in the user's language. Translations come from JSON catalogs committed to your
+repository and shipped inside your package; nothing is downloaded or executed at runtime, and a CLI
+without a matching catalog behaves exactly as before.
+
+The catalogs are written by [Localizer](https://locale.dev/): install the GitHub App or add the
+GitHub Action to your repository and it keeps a pull request up to date with translations of every
+string it finds in your code. This package is the runtime half — the part that runs on your users'
+machines.
+
+```sh
+pip install localizer-py   # not "localizer", which is an unrelated project
+```
+
+Python 3.10 or newer, no dependencies. Works with Click 8.1+, Typer 0.17+ (including Typer's
+bundled Click) and the standard library's argparse.
+
+## One line
+
+Call `localize` after every command and option is registered, right before the app runs:
+
+```python
+import localizer
+
+# Typer
+app = typer.Typer()
+...
+if __name__ == "__main__":
+    localizer.localize(app, "yourcli.locales")
+    app()
+
+# Click
+@click.group()
+def cli(): ...
+
+def main():
+    localizer.localize(cli, "yourcli.locales")
+    cli()
+
+# argparse
+parser = argparse.ArgumentParser(prog="yourcli")
+...
+localizer.localize(parser, "yourcli.locales")
+args = parser.parse_args()
+```
+
+`"yourcli.locales"` names the package holding your catalogs (`yourcli/locales/ja.json`, …); a
+directory path or an `importlib.resources` Traversable works too. If your CLI builds its command
+tree in a factory, call `localize` where the finished app object is handed out — translation happens
+when help and errors are rendered, so commands registered later (plugins, lazy groups) are covered.
+
+What is translated: your help text and option descriptions, the framework's own messages (`Usage:`,
+`Show this message and exit.`, `Missing argument 'NAME'.`, `Aborted!`, prompts, argparse's `error:`
+lines — built-in catalogs for these ship in this package), the messages of exceptions your CLI
+raises, and whatever your program passes through the helpers below. Nothing else changes: command and
+option names, values, JSON/YAML output and logs stay as they are.
+
+## Your own messages
+
+```python
+from localizer import t, tf, error
+
+print(t("Nothing to do."))                          # exact lookup, or the English text
+print(tf("Added task {n}: {title!r}", n=3, title=s))  # translated format string, then .format()
+console.print(t(f"Deleted {count} files"))          # formatted text is matched against the catalog
+raise click.ClickException(error(exc))              # an exception's message, for display
+```
+
+`t` on a format string looks the template up exactly (call it before formatting, or use `tf`); on
+finished text it reverse-matches the catalog's templates, so `f"Deleted {count} files"` finds
+`Deleted {count} files` and keeps the number. `localizer.translate(text, localizer.Mode.ERROR)`
+does the same for chokepoints that receive already-formatted messages. Every helper returns its input
+unchanged when there is no translation and never raises.
+
+## Catalogs
+
+One file per language, named by BCP 47 tag, keyed by the exact English source string:
+
+```json
+{
+  "version": 1,
+  "language": "ja",
+  "format": "python",
+  "messages": {
+    "Add a task.": "タスクを追加します。",
+    "Added task {n}: {title!r}": "タスク {n} を追加しました: {title!r}"
+  }
+}
+```
+
+Localizer generates and maintains these; you review them like any other pull request. Make sure the
+JSON files are packaged: hatchling, poetry, flit, pdm and uv include them automatically, setuptools
+needs `[tool.setuptools.package-data] yourcli = ["locales/*.json"]`.
+
+## Language selection
+
+`LOCALIZER_LANG`, then `LC_ALL`, `LC_MESSAGES`, `LANG` (and `LANGUAGE`), then the operating system's
+preferred languages on macOS and Windows; the best available catalog wins, English is the default.
+`localize(app, ..., env_var="YOURCLI_LANG")` adds an application-specific override checked first;
+`language="de"` forces a language. Setting the variable to `off` keeps a CLI in English;
+`LOCALIZER_LANG=qps` pseudo-localizes every translatable string (`⟦Ûšáĝé:⟧`) so you can see what is
+covered without a catalog. `LOCALIZER_DEBUG=1` reports untranslated strings and swallowed hook errors
+on stderr; `LOCALIZER_DUMP=path.json` writes the help tree with a translated/untranslated flag per
+entry.
+
+Pin your tests to English so snapshots don't depend on the machine's locale:
+
+```python
+# conftest.py
+import os
+
+def pytest_configure(config):
+    os.environ.setdefault("LOCALIZER_LANG", "en")
+```
+
+## More
+
+- Documentation: https://locale.dev/ — [runtime reference](https://locale.dev/reference/runtime/),
+  [integration guide](https://locale.dev/guides/integration/)
+- Coding agents: point yours at https://locale.dev/AGENTS.md to integrate Localizer into a CLI
+- Source: https://github.com/DABH/localizer (`python/`); license: NCSA

localizer_py-0.5.0/localizer/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2026 Snizyx Software LLC. All rights reserved.
+# SPDX-License-Identifier: NCSA
+
+"""Render a Typer, Click or argparse CLI's own strings in the user's language.
+
+The usual integration is one line before the app runs::
+
+    import localizer
+    localizer.localize(app, "yourcli.locales")
+
+where ``yourcli/locales/`` holds one ``<language>.json`` catalog per language (see
+https://locale.dev/reference/catalogs/). Language selection follows ``LOCALIZER_LANG`` (or an
+application-specific variable given as ``env_var``), then ``LC_ALL``, ``LC_MESSAGES``, ``LANG``, then the
+operating system's preferred languages; ``LOCALIZER_LANG=off`` disables localization and
+``LOCALIZER_LANG=qps`` pseudo-localizes every known string.
+
+Messages your own code prints go through :func:`t` (or :func:`tf` for format strings) at your output
+chokepoints; :func:`error` translates an exception for display. Everything fails open to English.
+"""
+
+from ._api import ENV_LANG, Mode, error, init, lang, localize, t, tf, translate, uninstall
+
+try:
+    from ._version import __version__
+except ImportError:  # a source checkout without the build hook
+    __version__ = "0.0.0"
+
+__all__ = ["ENV_LANG", "Mode", "__version__", "error", "init", "lang", "localize", "t", "tf", "translate", "uninstall"]

localizer_py-0.5.0/localizer/_api.py

@@ -0,0 +1,216 @@
+# Copyright (c) 2026 Snizyx Software LLC. All rights reserved.
+# SPDX-License-Identifier: NCSA
+
+"""The public API: language selection, the engine, and the helpers a CLI calls at its output points.
+
+Everything here fails open: an internal error leaves the CLI in English and never raises into the
+host program.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from . import _catalog, _locale, builtin
+from ._catalog import Traversable
+from ._engine import Engine, Mode
+
+__all__ = ["ENV_LANG", "Mode", "State", "state", "init", "localize", "t", "tf", "error", "translate", "lang", "uninstall"]
+
+ENV_LANG = "LOCALIZER_LANG"
+
+
+@dataclass
+class State:
+    engine: Engine
+    lang: str
+    debug: bool
+    dump: str  # LOCALIZER_DUMP path or ""
+
+
+_state: State | None = None
+_hooks_installed = False
+
+
+def state() -> State | None:
+    """The active state, or None when output stays in English."""
+    return _state
+
+
+def debug_enabled() -> bool:
+    return (os.environ.get("LOCALIZER_DEBUG") or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def debugf(msg: str) -> None:
+    if _state is not None and _state.debug or debug_enabled():
+        print("localizer: " + msg, file=sys.stderr)
+
+
+def debug_exc(where: str) -> None:
+    """Reports a swallowed exception when LOCALIZER_DEBUG is on."""
+    if debug_enabled():
+        print(f"localizer: {where}: {traceback.format_exc().strip().splitlines()[-1]}", file=sys.stderr)
+
+
+_catalog_cache: dict[tuple[object, str], dict[str, str]] = {}
+
+
+def _load_messages(root: Traversable, lang: str) -> dict[str, str]:
+    key = (str(root), lang)
+    msgs = _catalog_cache.get(key)
+    if msgs is None:
+        msgs = _catalog.load(root, lang).messages
+        _catalog_cache[key] = msgs
+    return msgs
+
+
+def _setup(locales, env_var: str | Sequence[str] | None, language: str | None) -> State | None:
+    override = [ENV_LANG]
+    if isinstance(env_var, str):
+        override.insert(0, env_var)
+    elif env_var:
+        override = [*env_var, ENV_LANG]
+    if language is not None:
+        res = _locale.detect(["_forced"], lambda _name: language)
+    else:
+        res = _locale.detect(override)
+    if res.off:
+        return None
+    root = _catalog.resolve(locales)
+    available = _catalog.languages(root)
+    debug = debug_enabled()
+    dump = os.environ.get("LOCALIZER_DUMP") or ""
+    if res.pseudo:
+        catalogs = [_load_messages(root, l) for l in available]
+        catalogs.extend(builtin.messages(l) for l in builtin.languages())
+        eng = Engine.pseudo(*catalogs)
+        return State(eng, "qps", debug, dump)
+    if not available:
+        return None
+    lang = _locale.match(res.tags, available)
+    if not lang:
+        return None
+    try:
+        app = _load_messages(root, lang)
+    except Exception:
+        debug_exc(f"loading the {lang} catalog")
+        return None
+    eng = Engine(lang, builtin.messages(lang), app)
+    if debug:
+
+        def on_miss(s: str, _mode: Mode) -> None:
+            first = s.strip().splitlines()[0] if s.strip() else s
+            print(f"localizer: untranslated ({lang}): {first!r}", file=sys.stderr)
+
+        eng.on_miss = on_miss
+    return State(eng, lang, debug, dump)
+
+
+def init(locales, *, env_var: str | Sequence[str] | None = None, language: str | None = None) -> str:
+    """Detects the user's language and loads the matching catalog from ``locales`` (a package name such
+    as "yourcli.locales", a directory, or a Traversable) for :func:`t`, :func:`tf`, :func:`error` and
+    :func:`translate`. Returns the selected language, or "" when output stays in English. Never raises.
+
+    ``env_var`` names an application-specific override variable (or several), consulted before
+    ``LOCALIZER_LANG``; ``language`` forces a language ("en" or "off" disables localization).
+    """
+    global _state
+    try:
+        _state = _setup(locales, env_var, language)
+    except Exception:
+        debug_exc("init")
+        _state = None
+    return _state.lang if _state else ""
+
+
+def localize(app, locales, *, env_var: str | Sequence[str] | None = None, language: str | None = None,
+             without_error_hook: bool = False, without_prompt_hook: bool = False) -> str:
+    """Localizes a Typer app, a Click command or an argparse parser: its help text, its framework's
+    own messages, the errors it prints and the prompts it shows, plus whatever the program passes
+    through :func:`t`. Call it after all commands and options are registered, right before the app
+    runs. Returns the selected language ("" for English). Never raises."""
+    global _hooks_installed
+    lang = init(locales, env_var=env_var, language=language)
+    if not _state:
+        return ""
+    try:
+        from . import _hooks
+
+        _hooks.install(app, error_hook=not without_error_hook, prompt_hook=not without_prompt_hook)
+        _hooks_installed = True
+    except Exception:
+        debug_exc("installing hooks")
+    return lang
+
+
+def uninstall() -> None:
+    """Removes every hook and forgets the language (for tests)."""
+    global _state, _hooks_installed
+    _state = None
+    if _hooks_installed:
+        try:
+            from . import _hooks
+
+            _hooks.uninstall()
+        except Exception:
+            debug_exc("uninstall")
+        _hooks_installed = False
+
+
+def lang() -> str:
+    """The active language tag ("qps" for pseudo-localization), or "" when output is English."""
+    return _state.lang if _state else ""
+
+
+def t(s: str) -> str:
+    """The translation of ``s``, or ``s`` unchanged. A format string is looked up exactly, so call
+    ``t`` before formatting: ``t("Created {name}").format(name=n)`` (or use :func:`tf`)."""
+    st = _state
+    if st is None or not isinstance(s, str) or s == "":
+        return s
+    try:
+        from . import _format
+
+        if _format.has_fields(s):
+            return st.engine.lookup(s)[0]
+        return st.engine.translate(s, Mode.OUTPUT)
+    except Exception:
+        debug_exc("t")
+        return s
+
+
+def tf(fmt: str, *args, **kwargs) -> str:
+    """``str.format`` with a translated format string; falls back to the English format if the
+    translation cannot be formatted with these arguments."""
+    tr = t(fmt)
+    try:
+        return tr.format(*args, **kwargs)
+    except Exception:
+        return fmt.format(*args, **kwargs)
+
+
+def translate(s: str, mode: Mode = Mode.OUTPUT) -> str:
+    """Translates text the CLI is about to print, splitting composite text as ``mode`` allows. Use it
+    at output chokepoints that receive already formatted messages."""
+    st = _state
+    if st is None or not isinstance(s, str) or s == "":
+        return s
+    try:
+        return st.engine.translate(s, mode)
+    except Exception:
+        debug_exc("translate")
+        return s
+
+
+def error(exc) -> str:
+    """The message of an exception (or a string) translated for display; the CLI's own parts of a
+    message are translated, text from servers and libraries stays as it is."""
+    try:
+        msg = exc.format_message() if hasattr(exc, "format_message") else str(exc)
+    except Exception:
+        msg = str(exc)
+    return translate(msg, Mode.ERROR)

localizer_py-0.5.0/localizer/_catalog.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2026 Snizyx Software LLC. All rights reserved.
+# SPDX-License-Identifier: NCSA
+
+"""Translation catalogs: one JSON file per language, named "<BCP 47 tag>.json", mapping each English
+source string to its translation. Catalogs ship inside the CLI's package and are read with
+importlib.resources, so they work from wheels, zip apps and source checkouts alike."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+try:
+    from importlib.resources.abc import Traversable
+except ImportError:  # Python 3.10
+    from importlib.abc import Traversable
+
+__all__ = ["File", "VERSION", "resolve", "languages", "load", "dumps"]
+
+VERSION = 1
+
+
+@dataclass
+class File:
+    """One language's catalog."""
+
+    language: str
+    messages: dict[str, str] = field(default_factory=dict)
+    version: int = VERSION
+    format: str = "python"  # placeholder syntax of the keys
+
+
+def resolve(locales: str | os.PathLike[str] | Traversable) -> Traversable:
+    """Turns a package name ("yourcli.locales"), a path or a Traversable into a Traversable."""
+    if isinstance(locales, str):
+        if os.sep in locales or "/" in locales or os.path.isdir(locales):
+            return Path(locales)
+        return resources.files(locales)
+    if isinstance(locales, os.PathLike):
+        return Path(locales)
+    return locales
+
+
+def languages(root: Traversable) -> list[str]:
+    """The catalog languages in ``root``: "<tag>.json" files, ignoring "_"- and "."-prefixed names."""
+    try:
+        entries = list(root.iterdir())
+    except (OSError, TypeError, AttributeError):
+        return []
+    out = []
+    for e in entries:
+        name = e.name
+        if not name.endswith(".json") or name.startswith(("_", ".")):
+            continue
+        try:
+            if not e.is_file():
+                continue
+        except OSError:
+            continue
+        out.append(name[: -len(".json")])
+    return sorted(out)
+
+
+def load(root: Traversable, lang: str) -> File:
+    """Reads the catalog for ``lang`` from ``root``."""
+    data = (root / (lang + ".json")).read_text(encoding="utf-8")
+    raw = json.loads(data)
+    if not isinstance(raw, dict):
+        raise ValueError("catalog: not an object")
+    version = raw.get("version", VERSION)
+    if not isinstance(version, int) or version > VERSION:
+        raise ValueError(f"catalog: unsupported version {version!r} (this build understands up to {VERSION})")
+    messages = raw.get("messages") or {}
+    if not isinstance(messages, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in messages.items()):
+        raise ValueError("catalog: messages must map strings to strings")
+    return File(language=str(raw.get("language", lang)), messages=messages, version=version, format=str(raw.get("format", "")))
+
+
+def dumps(f: File) -> str:
+    """Renders a catalog canonically, byte for byte as the Go tooling does: version, language, format
+    (when set), then messages with sorted keys, two-space indent, raw UTF-8 and a trailing newline."""
+    doc: dict[str, object] = {"version": f.version or VERSION, "language": f.language}
+    if f.format:
+        doc["format"] = f.format
+    doc["messages"] = dict(sorted(f.messages.items(), key=lambda kv: kv[0].encode("utf-8")))
+    out = json.dumps(doc, ensure_ascii=False, indent=2)
+    # Go's encoder always escapes these two, which JSON parsers otherwise accept raw.
+    return out.replace("\u2028", "\\u2028").replace("\u2029", "\\u2029") + "\n"