refactor(gt-i18n): registration interface (#18)

Author: ErnestM1234

.sampo/changesets/haughty-king-tuonetar.md

@@ -0,0 +1,5 @@
+---
+pypi/gt-i18n: patch
+---
+
+refactor: string registration interface

Makefile

@@ -10,6 +10,7 @@ lint-fix:
 	uv run ruff check --fix .
 
 format:
+	uv run ruff check --fix .
 	uv run ruff format .
 
 format-check:

packages/gt-i18n/src/gt_i18n/translation_functions/_extract_variables.py

@@ -1,16 +1,27 @@
-"""Filter $-prefixed GT keys from options, returning user variables."""
+"""Filter GT-reserved keys from options, returning user variables."""
 
 from __future__ import annotations
 
+_GT_RESERVED_KEYS = frozenset(
+    {
+        "_context",
+        "_id",
+        "_max_chars",
+        "__hash",
+        "__source",
+        "__fallback",
+    }
+)
+
 
 def extract_variables(options: dict[str, object]) -> dict[str, object]:
-    """Return only user interpolation variables (non-$ keys).
+    """Return only user interpolation variables.
 
     Args:
-        options: The full kwargs dict which may contain ``$context``,
-            ``$id``, ``$max_chars``, etc.
+        options: The full kwargs dict which may contain GT-reserved keys
+            like ``_context``, ``_id``, ``_max_chars``, etc.
 
     Returns:
-        A new dict with only the user-provided variable keys.
+        A new dict with GT-reserved keys removed.
     """
-    return {k: v for k, v in options.items() if not k.startswith("$")}
+    return {k: v for k, v in options.items() if k not in _GT_RESERVED_KEYS}

packages/gt-i18n/src/gt_i18n/translation_functions/_interpolate.py

@@ -25,15 +25,15 @@ def interpolate_message(
 
     Mirrors JS ``interpolateMessage()`` behavior:
 
-    1. Extract user variables (filter out ``$``-prefixed keys).
+    1. Extract user variables (filter out GT-reserved keys).
     2. Extract ``_gt_`` declared variables from the source/fallback.
     3. Condense ``_gt_`` selects to simple refs (only if declared vars exist).
     4. Format with ICU MessageFormat.
-    5. Apply ``$max_chars`` cutoff if specified.
+    5. Apply ``_max_chars`` cutoff if specified.
 
     On error:
-    - If ``$_fallback`` (source) is available, recursively retry with
-      the source message (clearing ``$_fallback`` to prevent infinite loop).
+    - If ``__fallback`` (source) is available, recursively retry with
+      the source message (clearing ``__fallback`` to prevent infinite loop).
     - Otherwise, return the raw message with cutoff applied.
 
     Args:
@@ -44,8 +44,8 @@ def interpolate_message(
     Returns:
         The interpolated string.
     """
-    source = options.get("$_fallback")
-    max_chars = options.get("$max_chars")
+    source = options.get("__fallback")
+    max_chars = options.get("_max_chars")
 
     # Remove GT-related options, keep user variables
     variables = extract_variables(options)
@@ -83,7 +83,7 @@ def interpolate_message(
         if source is not None and isinstance(source, str):
             return interpolate_message(
                 source,
-                {**options, "$_fallback": None},
+                {**options, "__fallback": None},
                 locale,
             )
 

packages/gt-i18n/src/gt_i18n/translation_functions/_is_encoded.py

@@ -4,5 +4,5 @@
 
 
 def is_encoded_translation_options(decoded_options: dict[str, object]) -> bool:
-    """Return True if the dict contains both ``$_hash`` and ``$_source``."""
-    return bool(decoded_options.get("$_hash") and decoded_options.get("$_source"))
+    """Return True if the dict contains both ``__hash`` and ``__source``."""
+    return bool(decoded_options.get("__hash") and decoded_options.get("__source"))

packages/gt-i18n/src/gt_i18n/translation_functions/_msg.py

@@ -29,15 +29,15 @@ def msg(message: str, **kwargs: object) -> str:
     except Exception:
         return message
 
-    # Build encoded options (preserve all kwargs including $-prefixed)
-    h = kwargs.get("$_hash") or hash_message(
+    # Build encoded options (preserve all kwargs including _-prefixed)
+    h = kwargs.get("__hash") or hash_message(
         message,
-        context=kwargs.get("$context"),  # type: ignore[arg-type]
-        id=kwargs.get("$id"),  # type: ignore[arg-type]
-        max_chars=kwargs.get("$max_chars"),  # type: ignore[arg-type]
+        context=kwargs.get("_context"),  # type: ignore[arg-type]
+        id=kwargs.get("_id"),  # type: ignore[arg-type]
+        max_chars=kwargs.get("_max_chars"),  # type: ignore[arg-type]
     )
 
-    encoded_options = {**kwargs, "$_source": message, "$_hash": h}
+    encoded_options = {**kwargs, "__source": message, "__hash": h}
     options_encoding = base64.b64encode(json.dumps(encoded_options, separators=(",", ":")).encode()).decode()
 
     return f"{interpolated}:{options_encoding}"

packages/gt-i18n/src/gt_i18n/translation_functions/_t.py

@@ -17,7 +17,7 @@ def t(message: str, **kwargs: object) -> str:
     Args:
         message: The ICU MessageFormat source string.
         **kwargs: Interpolation variables and GT options
-            (``$context``, ``$id``, ``$max_chars``).
+            (``_context``, ``_id``, ``_max_chars``).
 
     Returns:
         The translated and interpolated string.
@@ -31,13 +31,13 @@ def t(message: str, **kwargs: object) -> str:
     translations = manager.get_translations_sync(locale)
     h = hash_message(
         message,
-        context=kwargs.get("$context"),  # type: ignore[arg-type]
-        id=kwargs.get("$id"),  # type: ignore[arg-type]
-        max_chars=kwargs.get("$max_chars"),  # type: ignore[arg-type]
+        context=kwargs.get("_context"),  # type: ignore[arg-type]
+        id=kwargs.get("_id"),  # type: ignore[arg-type]
+        max_chars=kwargs.get("_max_chars"),  # type: ignore[arg-type]
     )
     translated = translations.get(h)
     if translated:
-        return interpolate_message(translated, {**kwargs, "$_fallback": message}, locale)
+        return interpolate_message(translated, {**kwargs, "__fallback": message}, locale)
 
     # No translation found — use source
     return interpolate_message(message, kwargs, locale)

packages/gt-i18n/tests/conftest.py

@@ -0,0 +1,6 @@
+"""Make the tests directory importable so helpers.py can be used."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))

packages/gt-i18n/tests/helpers.py

@@ -0,0 +1,37 @@
+"""Shared test helpers for converting JS-style fixture keys to Python-style."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+# Mapping from JS $-prefixed keys to Python _-prefixed keys
+JS_TO_PY_KEY_MAP: dict[str, str] = {
+    "$context": "_context",
+    "$id": "_id",
+    "$max_chars": "_max_chars",
+    "$_source": "__source",
+    "$_hash": "__hash",
+}
+
+
+def convert_keys(d: dict[str, Any]) -> dict[str, Any]:
+    """Convert JS-style $-prefixed keys to Python-style _-prefixed keys."""
+    return {JS_TO_PY_KEY_MAP.get(k, k): v for k, v in d.items()}
+
+
+def convert_encoded_string(encoded: str) -> str:
+    """Re-encode a JS-style encoded message with Python-style keys.
+
+    Takes 'message:base64payload', decodes the payload, converts
+    $-prefixed keys to _-prefixed, and re-encodes.
+    """
+    idx = encoded.rfind(":")
+    if idx == -1:
+        return encoded
+    msg_part = encoded[:idx]
+    payload = json.loads(base64.b64decode(encoded[idx + 1 :]).decode())
+    converted = convert_keys(payload)
+    new_b64 = base64.b64encode(json.dumps(converted, separators=(",", ":")).encode()).decode()
+    return f"{msg_part}:{new_b64}"

packages/gt-i18n/tests/test_extract_variables.py

@@ -1,15 +1,15 @@
-"""Tests for extract_variables ($-key filtering)."""
+"""Tests for extract_variables (_-key filtering)."""
 
 from gt_i18n.translation_functions._extract_variables import extract_variables
 
 
-def test_filters_dollar_keys() -> None:
-    opts: dict[str, object] = dict({"name": "Alice", "$context": "greeting", "$id": "hello"})
+def test_filters_underscore_keys() -> None:
+    opts: dict[str, object] = dict({"name": "Alice", "_context": "greeting", "_id": "hello"})
     result = extract_variables(opts)
     assert result == {"name": "Alice"}
 
 
-def test_keeps_all_non_dollar() -> None:
+def test_keeps_all_non_underscore() -> None:
     opts = {"name": "Alice", "count": 5, "item": "apples"}
     result = extract_variables(opts)
     assert result == opts
@@ -19,6 +19,12 @@ def test_empty_dict() -> None:
     assert extract_variables({}) == {}
 
 
-def test_all_dollar_keys() -> None:
-    opts = {"$context": "x", "$id": "y", "$max_chars": 10}
+def test_all_underscore_keys() -> None:
+    opts = {"_context": "x", "_id": "y", "_max_chars": 10}
     assert extract_variables(opts) == {}
+
+
+def test_user_underscore_prefixed_keys_preserved() -> None:
+    opts: dict[str, object] = {"_name": "Alice", "_context": "greeting"}
+    result = extract_variables(opts)
+    assert result == {"_name": "Alice"}