localizer-py 0.5.0__py3-none-any.whl

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/_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/_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"

localizer/_dump.py

@@ -0,0 +1,116 @@
+# Copyright (c) 2026 Snizyx Software LLC. All rights reserved.
+# SPDX-License-Identifier: NCSA
+
+"""LOCALIZER_DUMP: every help string of the command tree, with whether it was translated, written once
+per process as JSON in the same shape the Go runtime writes (for coverage reports)."""
+
+from __future__ import annotations
+
+import json
+
+from . import _api
+from ._engine import Mode
+
+_done: set[str] = set()
+
+
+def _write(entries: list[dict]) -> None:
+    st = _api.state()
+    if st is None or not st.dump:
+        return
+    doc = {"language": st.lang, "entries": entries}
+    with open(st.dump, "w", encoding="utf-8") as f:
+        json.dump(doc, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+
+
+def _entry(entries: list[dict], kind: str, command: str, text, flag: str = "") -> None:
+    st = _api.state()
+    if not isinstance(text, str) or not text.strip():
+        return
+    e = {"kind": kind, "command": command, "text": text}
+    if flag:
+        e["flag"] = flag
+    if st is not None:
+        e["translated"] = st.engine.translate(text, Mode.HELP) != text
+    entries.append(e)
+
+
+def maybe_dump_click(ctx) -> None:
+    """Dumps the tree reachable from the root of a Click context, the first time help renders."""
+    st = _api.state()
+    if st is None or not st.dump or "click" in _done:
+        return
+    _done.add("click")
+    root_ctx = ctx.find_root()
+    entries: list[dict] = []
+    _walk_click(root_ctx.command, root_ctx, entries)
+    _write(entries)
+
+
+def _walk_click(cmd, ctx, entries: list[dict]) -> None:
+    path = ctx.command_path
+    _entry(entries, "short", path, getattr(cmd, "short_help", None) or _first_paragraph(getattr(cmd, "help", None)))
+    _entry(entries, "long", path, getattr(cmd, "help", None))
+    _entry(entries, "epilog", path, getattr(cmd, "epilog", None))
+    if isinstance(getattr(cmd, "deprecated", None), str):
+        _entry(entries, "deprecated", path, cmd.deprecated)
+    if isinstance(getattr(cmd, "rich_help_panel", None), str):
+        _entry(entries, "group", path, cmd.rich_help_panel)
+    seen = set()
+    try:
+        params = cmd.get_params(ctx)
+    except Exception:
+        params = getattr(cmd, "params", [])
+    for p in params:
+        name = getattr(p, "name", "") or ""
+        if name in seen:
+            continue
+        seen.add(name)
+        _entry(entries, "flag", path, getattr(p, "help", None), name)
+        if isinstance(getattr(p, "rich_help_panel", None), str):
+            _entry(entries, "group", path, p.rich_help_panel, name)
+    if hasattr(cmd, "list_commands") and hasattr(cmd, "get_command"):
+        for name in cmd.list_commands(ctx):
+            sub = cmd.get_command(ctx, name)
+            if sub is None:
+                continue
+            try:
+                sub_ctx = type(ctx)(sub, info_name=name, parent=ctx)
+            except Exception:
+                continue
+            _walk_click(sub, sub_ctx, entries)
+
+
+def _first_paragraph(text):
+    if not isinstance(text, str):
+        return None
+    return text.strip().split("\n\n", 1)[0]
+
+
+def maybe_dump_argparse(parser) -> None:
+    st = _api.state()
+    if st is None or not st.dump or "argparse" in _done:
+        return
+    _done.add("argparse")
+    entries: list[dict] = []
+    _walk_argparse(parser, parser.prog, entries)
+    _write(entries)
+
+
+def _walk_argparse(parser, path: str, entries: list[dict]) -> None:
+    import argparse
+
+    _entry(entries, "long", path, parser.description)
+    _entry(entries, "epilog", path, parser.epilog)
+    for group in getattr(parser, "_action_groups", ()):
+        _entry(entries, "group", path, group.title)
+    for action in getattr(parser, "_actions", ()):
+        if action.help is argparse.SUPPRESS:
+            continue
+        flag = action.option_strings[0] if action.option_strings else action.dest
+        _entry(entries, "flag", path, action.help, flag)
+        choices = getattr(action, "choices", None)
+        if isinstance(action, argparse._SubParsersAction) and isinstance(choices, dict):
+            for name, sub in choices.items():
+                _walk_argparse(sub, f"{path} {name}", entries)