gettext-tstrings 0.1.0a1__tar.gz

gettext_tstrings-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest --cov=gettext_tstrings --cov-report=term-missing
+      - run: uv build
+      - name: Smoke test the built wheel in a clean environment
+        shell: bash
+        run: |
+          uv venv smoke
+          if [ -x smoke/bin/python ]; then PY=smoke/bin/python; else PY=smoke/Scripts/python.exe; fi
+          uv pip install --python "$PY" dist/*.whl
+          cat > smoke_check.py <<'EOF'
+          import gettext_tstrings
+
+          name = "World"
+          assert gettext_tstrings.tr(t"Hello {name}") == "Hello World"
+          print("smoke OK", gettext_tstrings.__version__)
+          EOF
+          "$PY" smoke_check.py

gettext_tstrings-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - name: Check tag matches package version
+        run: |
+          VERSION=$(grep -oE '__version__ = "[^"]+"' src/gettext_tstrings/__init__.py | cut -d'"' -f2)
+          test "$GITHUB_REF_NAME" = "v$VERSION" || {
+            echo "tag $GITHUB_REF_NAME does not match __version__ $VERSION" >&2
+            exit 1
+          }
+      - run: uv build
+      - name: Smoke test the built wheel in a clean environment
+        run: |
+          uv venv smoke --python 3.14
+          uv pip install --python smoke/bin/python dist/*.whl
+          cat > smoke_check.py <<'EOF'
+          import gettext_tstrings
+
+          name = "World"
+          assert gettext_tstrings.tr(t"Hello {name}") == "Hello World"
+          print("smoke OK", gettext_tstrings.__version__)
+          EOF
+          smoke/bin/python smoke_check.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

gettext_tstrings-0.1.0a1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.mo

gettext_tstrings-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.14

gettext_tstrings-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0a1 - 2026-07-28
+
+First public release.
+
+- Add safe `tr()` and `ntr()` runtimes for Python t-strings.
+- Add a Babel extractor that coexists with ordinary gettext calls.
+- Add strict placeholder validation as a Babel checker.
+- Preserve source-controlled conversions and format specifications.
+- Add canonical `gettext`, `ngettext`, `pgettext`, and `npgettext` APIs.
+- Cache static template and translated-pattern plans on the runtime hot path.
+- Support branch-specific plural placeholders and safe translated repetition.
+- Lenient runtime rendering: a catalog whose placeholders do not match the source falls back to the source text instead of raising; `strict=True` restores the raising behavior (on `Translator` and every module function).
+- Guard the empty-msgid trap so `t""` renders as `""` instead of returning the catalog header.
+- Extraction does not abort the whole run on one rejected t-string or one unparsable file; such calls warn and are skipped, with an opt-in `strict` extractor option.
+- Emit simple t-string messages with no funcname so extraction works under custom Babel keyword sets (e.g. `--no-default-keywords -k tr`); plural/contextual messages without the standard gettext keywords are skipped with a warning.
+- Add context-scoped current translations (`use_translations`, `set_translations`, `get_translations`) for per-request language selection.
+- Add deferred translation (`lazy_gettext`, `lazy_pgettext`, `LazyString`) for module-level translatable strings, extracted by default with an example-driven extraction-to-runtime round-trip test.
+- Make `LazyString` unhashable: its rendered text depends on the active language, so a hash would silently break sets and dict keys across switches.
+- Make the `Translations` protocol `runtime_checkable`.
+- Improve confusable-placeholder diagnostics with escaped names.
+- Document the t-string→msgid convention as a versioned contract (SPEC.md).
+- State the measured sub-microsecond overhead instead of claiming "fast".
+- Run CI on Linux, macOS, and Windows, and smoke-test the built wheel in a clean environment.
+- Add a tag-triggered release workflow using PyPI Trusted Publishing (see RELEASING.md).

gettext_tstrings-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for helping improve `gettext-tstrings`. The project is deliberately small:
+it is the connection convention between Python t-strings and gettext, not a new
+i18n framework. Changes are judged against that scope.
+
+## The convention comes first
+
+[SPEC.md](SPEC.md) defines the t-string→msgid derivation and the translation
+validation rules as a versioned contract. Any change to how a msgid is derived,
+or to which translations are accepted or rejected, is a change to the spec:
+update `SPEC.md` in the same pull request and explain why the version does or
+does not need to increment.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) and requires Python 3.14+.
+
+```console
+uv sync
+uv run ruff format .
+uv run ruff check .
+uv run mypy
+uv run pytest --cov=gettext_tstrings --cov-report=term-missing
+```
+
+All five must pass, matching CI. New behavior needs tests, and behavior that
+touches the spec needs tests that read like executable examples of the rule.
+
+## Guidelines
+
+- **Keep it narrow.** Prefer the simplest change that closes a concrete gap
+  backed by a real failure, test, or user need. New configuration, layers, or
+  branches need a strong justification.
+- **Never evaluate a translation.** The safety guarantee — no evaluation, no
+  attribute access, no calls, no translation-side formatting — is the core of
+  the project. Code that renders catalog data must go through the existing
+  validated path.
+- **Match the surrounding code.** Docstrings and comments in this repository are
+  written in Japanese; follow that convention.
+- **gettext parity.** The public API mirrors stdlib gettext naming and calling
+  conventions; new surface should extend that, not diverge from it.

gettext_tstrings-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Hayashi
+
+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.

gettext_tstrings-0.1.0a1/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: gettext-tstrings
+Version: 0.1.0a1
+Summary: Safe gettext and Babel integration for Python t-strings
+Project-URL: Homepage, https://github.com/yhay81/gettext-tstrings
+Project-URL: Issues, https://github.com/yhay81/gettext-tstrings/issues
+Author-email: Yusuke Hayashi <yusuke8h@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: babel,gettext,i18n,internationalization,t-strings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Internationalization
+Requires-Python: >=3.14
+Requires-Dist: babel>=2.18
+Description-Content-Type: text/markdown
+
+# gettext-tstrings
+
+Safe gettext integration for Python 3.14+ t-strings, with first-class
+[Babel](https://babel.pocoo.org/) extraction and validation.
+
+```python
+import gettext
+
+from gettext_tstrings import Translator
+
+_ = Translator(gettext.translation("messages", localedir="locales"))
+name = "Ada"
+print(_(t"Hello {name}"))
+```
+
+The catalog receives the complete sentence `Hello {name}`. A translation may
+reorder or repeat `{name}`, while the runtime rejects missing, unknown, or
+modified placeholders.
+
+## Why
+
+Python t-strings preserve the static text, evaluated values, source expressions,
+conversions, and format specifications separately. That makes them a useful
+boundary for internationalization, but gettext and Babel do not define how a
+t-string becomes a catalog message.
+
+`gettext-tstrings` makes one deliberately narrow choice:
+
+- translate complete messages, never sentence fragments;
+- accept only simple variable names such as `{name}`;
+- keep `!r` and `:.2f` formatting under application control;
+- let translators reorder and repeat known placeholders, but not execute
+  attribute access or add formatting behavior;
+- reuse normal POT, PO, and MO files.
+
+## Install
+
+```console
+python -m pip install gettext-tstrings
+```
+
+Python 3.14 or newer is required.
+
+## Pythonic runtime API
+
+The recommended API mirrors gettext's class-based usage. Bind a standard
+translation object once and use the callable processor as `_`:
+
+```python
+import gettext
+
+from gettext_tstrings import Translator
+
+translations = gettext.translation(
+    "messages",
+    localedir="locales",
+    languages=["ja"],
+)
+
+_ = Translator(translations)
+
+name = "Ada"
+print(_(t"Hello {name}"))
+
+n = 3
+print(_.ngettext(t"One file", t"{n} files", n))
+
+filename = "report.txt"
+print(_.pgettext("button", t"Open {filename}"))
+```
+
+The module-level API follows the standard library names and positional-only
+calling convention:
+
+```python
+from gettext_tstrings import gettext, ngettext, npgettext, pgettext
+
+gettext(t"Hello {name}", translations=translations)
+ngettext(t"One file", t"{n} files", n, translations=translations)
+pgettext("button", t"Open {filename}", translations=translations)
+npgettext(
+    "inbox",
+    t"One message",
+    t"{n} messages",
+    n,
+    translations=translations,
+)
+```
+
+`tr` and `ntr` are exact aliases of `gettext` and `ngettext`. When an explicit
+translation object is omitted, module-level functions use the translations bound
+to the current context (see [Per-request language](#per-request-language)), and
+otherwise fall back to the standard library's globally installed gettext
+functions.
+
+Plural branches may expose different values. This common form is valid:
+
+```python
+ngettext(t"One file", t"{n} files", n)
+```
+
+Fields present in both source branches are required in every translated plural
+form. A field present in only one branch is available but optional, allowing a
+language's plural rules to differ from the source language.
+
+Conversions and format specs stay outside the catalog:
+
+```python
+amount = 1234.5
+tr(t"Total: {amount:,.2f}")
+# msgid: "Total: {amount}"
+```
+
+## Per-request language
+
+Web frameworks pick a language per request. Bind the request's translations to
+the current context and the module-level functions (and any `_` that calls them)
+resolve to that language, safely across concurrent requests:
+
+```python
+from gettext_tstrings import tr, use_translations
+
+
+def handle(request):
+    translations = load_translations(request.locale)  # your gettext.translation(...)
+    with use_translations(translations):
+        return render(tr(t"Hello {name}"))
+```
+
+`set_translations(translations)` binds without a `with` block (for frameworks
+that manage the request lifecycle themselves), and `get_translations()` reads
+the current binding. An explicit `translations=` argument always wins over the
+context. A bound `Translator` is the alternative when you prefer to thread one
+object through your call sites explicitly.
+
+## Deferred (lazy) translation
+
+A t-string captures its values eagerly, which is wrong for a string defined at
+import time — a form label, an enum value, a module constant — that must render
+in whatever language is active when it is *used*. `lazy_gettext` defers the
+catalog lookup and rendering to first use, resolving the current context:
+
+```python
+from gettext_tstrings import lazy_gettext, lazy_pgettext, use_translations
+
+SAVE = lazy_gettext(t"Save changes")  # defined once, at import
+OPEN = lazy_pgettext("button", t"Open file")
+
+with use_translations(japanese):
+    assert str(SAVE) == "変更を保存"  # rendered here, in this language
+```
+
+A `LazyString` renders through `str()`, `format()`, and f-strings, and compares
+equal to its rendered text. Plural forms depend on a runtime count, so render
+those eagerly with `ngettext` where the count is known.
+
+## Broken catalogs never crash a render
+
+If a translation's placeholders do not match the source — a missing, unknown, or
+reformatted field slipping past validation (a hand-edited MO, a vendor catalog,
+a pipeline that skips the checker) — the default is to reproduce the source text
+rather than raise, mirroring gettext's contract that a bad catalog never breaks
+the application. A warning is logged on the `gettext_tstrings` logger.
+
+Opt into fail-loud behavior for tests and CI:
+
+```python
+_ = Translator(translations, strict=True)  # raises InvalidTranslationError
+tr(t"Hello {name}", translations=translations, strict=True)
+```
+
+## Extract with Babel
+
+Create `babel.cfg`:
+
+```ini
+[gettext_tstrings: **.py]
+encoding = utf-8
+```
+
+Then use the normal Babel workflow:
+
+```console
+pybabel extract -F babel.cfg -o locales/messages.pot .
+pybabel init -i locales/messages.pot -d locales -l ja
+pybabel compile -d locales
+```
+
+The `gettext_tstrings` extractor also extracts ordinary `_()`, `gettext()`,
+and `ngettext()` calls, so one mapping can cover mixed codebases.
+
+The extractor recognizes `_()`, the four standard gettext names, the
+`tr()` / `ntr()` aliases, and the deferred `lazy_gettext()` / `lazy_pgettext()`.
+Additional aliases can be configured:
+
+```ini
+[gettext_tstrings: **.py]
+tr_functions = tr, translate
+ntr_functions = ntr, pluralize
+gettext_functions = gettext, _, lazy_gettext
+ngettext_functions = ngettext
+pgettext_functions = pgettext, lazy_pgettext
+npgettext_functions = npgettext
+```
+
+All `Translator` methods are recognized regardless of the variable name.
+Callable processors named `_` are recognized by default; add another callable
+variable name to `gettext_functions` if needed.
+
+### Registering t-string functions
+
+t-string calls are recognized through the `*_functions` mapping options above,
+**not** through Babel's `-k`/`--keyword` flag. A t-string literal cannot be read
+by Babel's built-in keyword machinery, so a custom helper such as `mytr(t"...")`
+must be listed in `tr_functions` (or the matching option) — `-k mytr` alone will
+not extract it. The `-k` flag continues to work for ordinary (non-t-string)
+gettext calls, which are extracted alongside.
+
+Only the standard gettext argument order is supported (message first; context
+then message for `pgettext`; context, singular, plural for `npgettext`). Wrappers
+with non-standard argument positions are not configurable.
+
+### Robust by default
+
+- A t-string the extractor rejects (attribute access, an expression, a wrong
+  argument) is **warned about and skipped**; it never aborts extraction of the
+  rest of the project. An unparsable file is skipped the same way. Set
+  `strict = true` in the mapping to fail the run instead.
+- Simple messages extract under **any** keyword set, including
+  `pybabel extract --no-default-keywords -k tr`. Plural and contextual messages
+  need Babel's canonical keyword specs, so keep `ngettext`, `pgettext`, and
+  `npgettext` in the keyword set (the default set already has them); otherwise
+  those messages are skipped with a warning.
+
+Translator comments work as usual:
+
+```python
+# Translators: Product name shown in the account header.
+tr(t"Welcome, {product_name}")
+```
+
+Every extracted t-string message carries an automatic `gettext-tstrings`
+comment. The installed Babel checker uses that marker to reject incompatible
+placeholders and translation-controlled formatting during catalog validation
+and compilation.
+
+## Performance
+
+The overhead is sub-microsecond per call: roughly 0.7 µs for a one-field
+message on Apple Silicon, a few times a plain `gettext(...).format(...)`. That
+difference buys placeholder validation, safe rendering, and the structural
+guarantees above — this library optimizes for safety per nanosecond, not for
+beating `str.format`.
+
+The runtime separates static structure from dynamic values as intended by
+PEP 750:
+
+- template plans are cached by static strings, expressions, conversions, and
+  format specifications;
+- translated brace patterns are parsed and validated once;
+- both caches are bounded and never retain interpolated values;
+- each distinct value is formatted at most once per render, even when a
+  translation repeats its placeholder;
+- one-field and constant messages use specialized rendering paths.
+
+Run the reproducible microbenchmark on your target interpreter and hardware:
+
+```console
+uv run python benchmarks/runtime.py
+```
+
+## Safety and scope
+
+This is valid:
+
+```python
+tr(t"Hello {name}")
+```
+
+These are intentionally rejected:
+
+```python
+tr(t"Hello {user.name}")  # attribute access
+tr(t"Hello {display_name()}")  # function call
+```
+
+Compute a meaningful value first:
+
+```python
+name = user.display_name()
+tr(t"Hello {name}")
+```
+
+This restriction produces stable catalog keys, gives translators useful names,
+and prevents translated strings from becoming an expression language.
+
+The safety guarantee is scoped to *structure and formatting*: a translation is
+never evaluated, and can never add attribute access, calls, conversions, or
+format specs. Two things stay the caller's responsibility, exactly as with
+stdlib gettext: **escaping** rendered output for its sink (HTML, shell,
+terminal), and **catalog integrity** — a hostile catalog can repeat a
+placeholder to amplify output size, which is inherent to any placeholder-based
+i18n and is not bounded here.
+
+## Templates and other tools
+
+t-strings are Python syntax, so this library covers Python source. Template
+languages (Jinja2, Django templates) keep using their own `{% trans %}` /
+`{{ _(...) }}` i18n and Babel's template extractors; both feed the **same** PO
+catalog, so one translation workflow covers a mixed codebase.
+
+`pygettext` cannot parse t-strings today, so extraction goes through Babel. The
+t-string→msgid convention is written down as a small, versioned contract in
+[SPEC.md](SPEC.md) so that other extractors, IDEs, type checkers, or a future
+`pygettext` can target it.
+
+## Status
+
+The project is an alpha. Its core contract is small on purpose; the
+[specification](SPEC.md) is the stable reference. Before a stable release it will
+add broader language fixtures, sustained performance tracking, API review from
+gettext/Babel users, and compatibility testing against every supported Python
+and Babel release.
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).