autolang 0.1.0__tar.gz

autolang-0.1.0/LICENSE

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

autolang-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: autolang
+Version: 0.1.0
+Summary: Transparent i18n for Python f-strings.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: babel>=2.18.0
+Requires-Dist: executing>=2.2.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Autolang
+
+`Autolang` is an experimental i18n library for Python `f-string` call sites.
+It lets you bind a module-level `tt` function, write `tt(f"...")`, reconstruct the original template at runtime, look up a translated template from TOML, and re-evaluate the translated placeholders with Babel-aware formatting.
+
+## Status
+
+This project is under active development.
+
+Stable today:
+- `install(locale, locale_dir)` to create an isolated translator instance
+- `TransparentTranslator` for explicit instances
+- TOML-backed translation lookup
+- Babel `fmt.*` placeholder support inside translated templates
+- Per-instance call-site cache with `reload()` and `clear_cache()`
+- `tt init` and `tt sync` for locale template bootstrapping and synchronization
+
+Planned:
+- AI-assisted translation generation
+- Better extraction and review workflows
+
+## Installation
+
+```bash
+pip install autolang
+```
+
+## Quick Start
+
+Project layout:
+
+```text
+your_app/
+  app.py
+  locales/
+    es.toml
+```
+
+`locales/es.toml`
+
+```toml
+"Hello {name}" = "Hola {name}"
+"Today is {fmt.date(now, format='short')}" = "Hoy es {fmt.date(now, format='short')}"
+```
+
+`app.py`
+
+```python
+from datetime import datetime
+
+from babel import Locale
+from babel.support import Format
+
+from autolang import install
+
+translator = install("es", "locales")
+tt = translator.translate
+
+# A local fmt object keeps the original f-string valid before translation happens.
+fmt = Format(Locale.parse("en"))
+
+name = "Alice"
+now = datetime(2026, 3, 11)
+
+print(tt(f"Hello {name}"))
+print(tt(f"Today is {fmt.date(now, format='short')}"))
+```
+
+Example output:
+
+```text
+Hola Alice
+Hoy es 11/3/26
+```
+
+## Public API
+
+```python
+from autolang import (
+    TransparentTranslator,
+    install,
+)
+```
+
+- `install(locale_str, locale_dir="locales")` creates and returns a translator instance.
+- `TransparentTranslator(locale_str, locale_dir="locales")` creates an explicit translator instance with its own cache.
+- `translator.translate(text)` translates the current call site.
+- `translator.reload()` reloads the instance locale file and clears its cached call-site entries.
+- `translator.clear_cache()` clears the instance cache without reloading files.
+
+## Module Setup
+
+The recommended pattern is to initialize a module-level `tt` variable once and then call `tt(...)` everywhere in that module.
+
+```python
+from autolang import install
+
+translator = install("es", "locales")
+tt = translator.translate
+```
+
+## CLI
+
+The project also ships a short developer CLI command: `tt`.
+
+Translate all locale TOML files by filling entries still marked as `NO_TRANSLATION` through an OpenAI-compatible API:
+
+```bash
+tt translate \
+  --locale-dir locales \
+  --model gpt-4.1-mini \
+  --api-key "$OPENAI_API_KEY"
+```
+
+By default, the command:
+- discovers every `*.toml` file under the locale directory as a translation target
+- uses each TOML key as the source template text
+- reads cue text from `.<locale-dir>_cue/*.toml` when available
+- assumes keys may be mixed-language and lets the model decide per item whether translation is needed
+- only translates locale entries whose current value is `NO_TRANSLATION`
+- sends translation requests in batches and can execute multiple batches concurrently
+- validates returned JSON and placeholder compatibility before writing files
+
+Useful flags:
+- `--overwrite` to force re-translation of existing target values
+- `--dry-run` to preview work without writing files
+- `--batch-size 20` to control how many entries are sent in one model request
+- `--workers 4` to control concurrent batch requests
+- `--base-url` to point at any OpenAI-compatible endpoint
+
+The CLI also reads these environment variables:
+- `TT_API_KEY` or `OPENAI_API_KEY`
+- `TT_BASE_URL` or `OPENAI_BASE_URL`
+- `TT_MODEL` or `OPENAI_MODEL`
+
+Initialize locale TOML files from collected `tt(...)` templates:
+
+```bash
+tt init \
+  --source src \
+  --locale-dir locales \
+  --locales en es
+```
+
+By default, the command:
+- scans Python files under `--source`
+- extracts `tt("...")` and `tt(f"...")` call sites through a Babel-compatible extractor
+- skips hidden and cache/build directories such as `.git`, `.venv`, and `__pycache__`
+- creates one TOML file per requested locale
+- writes every collected key as `"source" = "NO_TRANSLATION"`
+- writes static cue entries into matching files under `.locales_cue/`
+- includes per-placeholder context such as the nearest assignment, parameter annotation, allowed `fmt.*` candidates, and a recommended candidate when confidence is high
+
+Sync collected templates across existing locale TOML files:
+
+```bash
+tt sync \
+  --source src \
+  --locale-dir locales
+```
+
+By default, the command:
+- scans Python files under `--source`
+- requires at least one existing `*.toml` locale file under `--locale-dir`
+- keeps existing translated values for keys that are still present in source
+- writes missing keys as `"source" = "NO_TRANSLATION"`
+- removes stale keys that are no longer collected from source
+- rewrites cue files under `.locales_cue/` to match the current template set
+
+## How It Works
+
+At a high level:
+
+1. You call `tt(f"...")`.
+   Here `tt = translator.translate`.
+2. The library inspects the caller frame and maps it back to the AST node for that exact call site.
+3. It rebuilds the source template, for example `Hello {name}`.
+4. It loads the translated template from TOML.
+5. It compiles the translated template as an f-string expression and caches it per translator instance.
+6. Later calls from the same bytecode location reuse the cached compiled expression.
+
+## Constraints
+
+This is not a drop-in replacement for mature gettext tooling yet.
+
+- The main path is designed for direct `tt(f"...")` usage after binding `tt = translator.translate`.
+- Library code should keep its own translator instance and bind its own `tt` function in module scope.
+- Translation lookup is currently a flat TOML key-value map.
+- Static cue collection writes analysis data into a sibling hidden directory such as `.locales_cue`.
+- If translated placeholder expressions are invalid or fail at evaluation time, the library falls back to the original rendered text.
+- The library currently relies on runtime frame inspection and AST recovery, so unusual execution environments may behave differently.
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest -q
+```
+
+## Roadmap
+
+- AI-generated translations from source templates and static cues
+- Locale file generation and diffing
+- Better developer tooling around extraction, validation, and review

autolang-0.1.0/README.md

@@ -0,0 +1,205 @@
+# Autolang
+
+`Autolang` is an experimental i18n library for Python `f-string` call sites.
+It lets you bind a module-level `tt` function, write `tt(f"...")`, reconstruct the original template at runtime, look up a translated template from TOML, and re-evaluate the translated placeholders with Babel-aware formatting.
+
+## Status
+
+This project is under active development.
+
+Stable today:
+- `install(locale, locale_dir)` to create an isolated translator instance
+- `TransparentTranslator` for explicit instances
+- TOML-backed translation lookup
+- Babel `fmt.*` placeholder support inside translated templates
+- Per-instance call-site cache with `reload()` and `clear_cache()`
+- `tt init` and `tt sync` for locale template bootstrapping and synchronization
+
+Planned:
+- AI-assisted translation generation
+- Better extraction and review workflows
+
+## Installation
+
+```bash
+pip install autolang
+```
+
+## Quick Start
+
+Project layout:
+
+```text
+your_app/
+  app.py
+  locales/
+    es.toml
+```
+
+`locales/es.toml`
+
+```toml
+"Hello {name}" = "Hola {name}"
+"Today is {fmt.date(now, format='short')}" = "Hoy es {fmt.date(now, format='short')}"
+```
+
+`app.py`
+
+```python
+from datetime import datetime
+
+from babel import Locale
+from babel.support import Format
+
+from autolang import install
+
+translator = install("es", "locales")
+tt = translator.translate
+
+# A local fmt object keeps the original f-string valid before translation happens.
+fmt = Format(Locale.parse("en"))
+
+name = "Alice"
+now = datetime(2026, 3, 11)
+
+print(tt(f"Hello {name}"))
+print(tt(f"Today is {fmt.date(now, format='short')}"))
+```
+
+Example output:
+
+```text
+Hola Alice
+Hoy es 11/3/26
+```
+
+## Public API
+
+```python
+from autolang import (
+    TransparentTranslator,
+    install,
+)
+```
+
+- `install(locale_str, locale_dir="locales")` creates and returns a translator instance.
+- `TransparentTranslator(locale_str, locale_dir="locales")` creates an explicit translator instance with its own cache.
+- `translator.translate(text)` translates the current call site.
+- `translator.reload()` reloads the instance locale file and clears its cached call-site entries.
+- `translator.clear_cache()` clears the instance cache without reloading files.
+
+## Module Setup
+
+The recommended pattern is to initialize a module-level `tt` variable once and then call `tt(...)` everywhere in that module.
+
+```python
+from autolang import install
+
+translator = install("es", "locales")
+tt = translator.translate
+```
+
+## CLI
+
+The project also ships a short developer CLI command: `tt`.
+
+Translate all locale TOML files by filling entries still marked as `NO_TRANSLATION` through an OpenAI-compatible API:
+
+```bash
+tt translate \
+  --locale-dir locales \
+  --model gpt-4.1-mini \
+  --api-key "$OPENAI_API_KEY"
+```
+
+By default, the command:
+- discovers every `*.toml` file under the locale directory as a translation target
+- uses each TOML key as the source template text
+- reads cue text from `.<locale-dir>_cue/*.toml` when available
+- assumes keys may be mixed-language and lets the model decide per item whether translation is needed
+- only translates locale entries whose current value is `NO_TRANSLATION`
+- sends translation requests in batches and can execute multiple batches concurrently
+- validates returned JSON and placeholder compatibility before writing files
+
+Useful flags:
+- `--overwrite` to force re-translation of existing target values
+- `--dry-run` to preview work without writing files
+- `--batch-size 20` to control how many entries are sent in one model request
+- `--workers 4` to control concurrent batch requests
+- `--base-url` to point at any OpenAI-compatible endpoint
+
+The CLI also reads these environment variables:
+- `TT_API_KEY` or `OPENAI_API_KEY`
+- `TT_BASE_URL` or `OPENAI_BASE_URL`
+- `TT_MODEL` or `OPENAI_MODEL`
+
+Initialize locale TOML files from collected `tt(...)` templates:
+
+```bash
+tt init \
+  --source src \
+  --locale-dir locales \
+  --locales en es
+```
+
+By default, the command:
+- scans Python files under `--source`
+- extracts `tt("...")` and `tt(f"...")` call sites through a Babel-compatible extractor
+- skips hidden and cache/build directories such as `.git`, `.venv`, and `__pycache__`
+- creates one TOML file per requested locale
+- writes every collected key as `"source" = "NO_TRANSLATION"`
+- writes static cue entries into matching files under `.locales_cue/`
+- includes per-placeholder context such as the nearest assignment, parameter annotation, allowed `fmt.*` candidates, and a recommended candidate when confidence is high
+
+Sync collected templates across existing locale TOML files:
+
+```bash
+tt sync \
+  --source src \
+  --locale-dir locales
+```
+
+By default, the command:
+- scans Python files under `--source`
+- requires at least one existing `*.toml` locale file under `--locale-dir`
+- keeps existing translated values for keys that are still present in source
+- writes missing keys as `"source" = "NO_TRANSLATION"`
+- removes stale keys that are no longer collected from source
+- rewrites cue files under `.locales_cue/` to match the current template set
+
+## How It Works
+
+At a high level:
+
+1. You call `tt(f"...")`.
+   Here `tt = translator.translate`.
+2. The library inspects the caller frame and maps it back to the AST node for that exact call site.
+3. It rebuilds the source template, for example `Hello {name}`.
+4. It loads the translated template from TOML.
+5. It compiles the translated template as an f-string expression and caches it per translator instance.
+6. Later calls from the same bytecode location reuse the cached compiled expression.
+
+## Constraints
+
+This is not a drop-in replacement for mature gettext tooling yet.
+
+- The main path is designed for direct `tt(f"...")` usage after binding `tt = translator.translate`.
+- Library code should keep its own translator instance and bind its own `tt` function in module scope.
+- Translation lookup is currently a flat TOML key-value map.
+- Static cue collection writes analysis data into a sibling hidden directory such as `.locales_cue`.
+- If translated placeholder expressions are invalid or fail at evaluation time, the library falls back to the original rendered text.
+- The library currently relies on runtime frame inspection and AST recovery, so unusual execution environments may behave differently.
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest -q
+```
+
+## Roadmap
+
+- AI-generated translations from source templates and static cues
+- Locale file generation and diffing
+- Better developer tooling around extraction, validation, and review

autolang-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["uv_build >= 0.10.7, <0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "autolang"
+version = "0.1.0"
+description = "Transparent i18n for Python f-strings."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "babel>=2.18.0",
+    "executing>=2.2.1",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.scripts]
+tt = "autolang.cli:main"
+autolang = "autolang.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.38.2",
+    "ipykernel>=7.2.0",
+    "pytest>=9.0.2",
+    "pytest-benchmark>=5.2.3",
+    "ruff>=0.15.6",
+]

autolang-0.1.0/src/autolang/__init__.py

@@ -0,0 +1,6 @@
+from .translator import TransparentTranslator, install
+
+__all__ = [
+    "TransparentTranslator",
+    "install",
+]

autolang-0.1.0/src/autolang/cli/__init__.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import argparse
+
+from . import init as _init
+from . import sync as _sync
+from . import translate as _translate
+
+BatchTranslationItem = _translate.BatchTranslationItem
+BatchTranslationOutcome = _translate.BatchTranslationOutcome
+BatchTranslationRequest = _translate.BatchTranslationRequest
+OpenAICompatibleClient = _translate.OpenAICompatibleClient
+PlaceholderSpec = _translate.PlaceholderSpec
+TranslationResult = _translate.TranslationResult
+TranslationTask = _translate.TranslationTask
+validate_translated_text = _translate.validate_translated_text
+
+
+def handle_translate_command(args: argparse.Namespace) -> int:
+    _translate.OpenAICompatibleClient = OpenAICompatibleClient
+    return _translate.handle_translate_command(args)
+
+
+def handle_sync_command(args: argparse.Namespace) -> int:
+    return _sync.handle_sync_command(args)
+
+
+def handle_init_command(args: argparse.Namespace) -> int:
+    return _init.handle_init_command(args)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tt", description="Autolang developer tools.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    translate_parser = subparsers.add_parser(
+        "translate",
+        help="Translate locale TOML files through an OpenAI-compatible API.",
+    )
+    translate_parser.add_argument("--locale-dir", default="locales")
+    translate_parser.add_argument("--model", default=None)
+    translate_parser.add_argument("--base-url", default=None)
+    translate_parser.add_argument("--api-key", default=None)
+    translate_parser.add_argument("--timeout", type=float, default=60.0)
+    translate_parser.add_argument("--workers", type=int, default=4)
+    translate_parser.add_argument("--batch-size", type=int, default=20)
+    translate_parser.add_argument("--overwrite", action="store_true")
+    translate_parser.add_argument("--dry-run", action="store_true")
+    translate_parser.set_defaults(handler=handle_translate_command)
+
+    sync_parser = subparsers.add_parser(
+        "sync",
+        help="Sync tt()-wrapped source templates across all locale TOML files.",
+    )
+    sync_parser.add_argument("--source", default=".")
+    sync_parser.add_argument("--locale-dir", default="locales")
+    sync_parser.add_argument("--dry-run", action="store_true")
+    sync_parser.set_defaults(handler=handle_sync_command)
+
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize locale TOML files from collected tt()-wrapped source templates.",
+    )
+    init_parser.add_argument("--source", default=".")
+    init_parser.add_argument("--locale-dir", default="locales")
+    init_parser.add_argument("--locales", nargs="+", required=True)
+    init_parser.add_argument("--force", action="store_true")
+    init_parser.add_argument("--dry-run", action="store_true")
+    init_parser.set_defaults(handler=handle_init_command)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+__all__ = [
+    "BatchTranslationItem",
+    "BatchTranslationOutcome",
+    "BatchTranslationRequest",
+    "OpenAICompatibleClient",
+    "PlaceholderSpec",
+    "TranslationResult",
+    "TranslationTask",
+    "build_parser",
+    "handle_init_command",
+    "handle_sync_command",
+    "handle_translate_command",
+    "main",
+    "validate_translated_text",
+]

autolang-0.1.0/src/autolang/cli/__main__.py

@@ -0,0 +1,5 @@
+from . import main
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

autolang-0.1.0/src/autolang/cli/common.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from babel import Locale
+
+from ..toml_io import load_string_table
+
+SKIPPED_SOURCE_DIR_NAMES = {
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+NO_TRANSLATION = "NO_TRANSLATION"
+
+
+def load_shared_cues(locale_dir: Path) -> dict[str, str]:
+    cue_dir = locale_dir.parent / f".{locale_dir.name}_cue"
+    merged_cues: dict[str, str] = {}
+    for cue_path in sorted(cue_dir.glob("*.toml")):
+        if not cue_path.is_file():
+            continue
+        for key, value in load_string_table(str(cue_path)).items():
+            merged_cues.setdefault(key, value)
+    return merged_cues
+
+
+def build_source_cue_path(locale_dir: Path, locale_name: str) -> Path:
+    cue_dir = locale_dir.parent / f".{locale_dir.name}_cue"
+    return cue_dir / f"{locale_name}.toml"
+
+
+def list_locale_files(locale_dir: Path) -> list[Path]:
+    return sorted(path for path in locale_dir.glob("*.toml") if path.is_file())
+
+
+def should_recurse_into_directory(path: str) -> bool:
+    name = Path(path).name
+    return not name.startswith(".") and name not in SKIPPED_SOURCE_DIR_NAMES
+
+
+def normalize_language(locale_name: str) -> str:
+    return Locale.parse(locale_name).language
+
+
+def locale_display_name(locale_name: str) -> str:
+    locale = Locale.parse(locale_name)
+    return locale.get_display_name("en").title()