i18n-fastapi 0.1.3__tar.gz

i18n_fastapi-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johnatan Palacios Londoño
+
+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.

i18n_fastapi-0.1.3/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: i18n-fastapi
+Version: 0.1.3
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Typing :: Typed
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: orjson>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
+Requires-Dist: httpx>=0.27.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.4.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.10.0 ; extra == 'dev'
+Requires-Dist: maturin>=1.5,<2.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0 ; extra == 'dev'
+Requires-Dist: watchfiles>=0.20.0 ; extra == 'reload'
+Provides-Extra: dev
+Provides-Extra: reload
+License-File: LICENSE
+Summary: High-performance i18n for FastAPI with Rust-powered translation engine
+Keywords: fastapi,i18n,internationalization,rust,translations
+Author-email: Johnatan Palacios Londoño <johnatan.palacios@utp.edu.co>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# i18n-fastapi
+
+[![PyPI version](https://img.shields.io/pypi/v/i18n-fastapi.svg)](https://pypi.org/project/i18n-fastapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/i18n-fastapi.svg)](https://pypi.org/project/i18n-fastapi/)
+[![License](https://img.shields.io/pypi/l/i18n-fastapi.svg)](https://github.com/johnatanpalacios/i18n-fastapi/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/johnatanpalacios/i18n-fastapi/ci.yml?branch=main&label=CI)](https://github.com/johnatanpalacios/i18n-fastapi/actions)
+
+High-performance internationalization for FastAPI, powered by a Rust translation engine with automatic Python fallback.
+
+## Features
+
+- **Rust-powered engine** — blazing-fast translation lookups via PyO3, with pure Python fallback
+- **ICU plural support** — zero / one / two / few / many / other
+- **Configurable locale detection** — query params, cookies, headers, path prefix, in any priority order
+- **Plugin pattern** — one-line setup with `I18n(app)`
+- **Multiple locale directories** — shared + per-module translations with filename-based namespacing
+- **Duplicate key detection** — catch conflicts at startup, not at runtime
+- **Hot reload** — watch translation files during development
+- **Built-in endpoint** — `GET /i18n/languages` returns available locales
+- **FastAPI dependencies** — inject `Locale` and `TranslateFunc` into route handlers
+
+## Installation
+
+```bash
+pip install i18n-fastapi
+```
+
+For hot reload during development:
+
+```bash
+pip install "i18n-fastapi[reload]"
+```
+
+## Quick Start
+
+Create translation files:
+
+```
+locales/
+├── en/
+│   └── messages.json    # {"greeting": "Hello {name}"}
+└── es/
+    └── messages.json    # {"greeting": "Hola {name}"}
+```
+
+Set up your app:
+
+```python
+from fastapi import FastAPI
+from i18n_fastapi import I18n, t
+
+app = FastAPI()
+I18n(app)
+
+@app.get("/greet")
+async def greet():
+    return {"message": t("messages.greeting", name="World")}
+```
+
+Request with `?lang=es` or `Accept-Language: es` and the response adapts automatically.
+
+## Documentation
+
+- **[Usage Guide](docs/USAGE.md)** — configuration, locale detection, pluralization, and more
+- **[Contributing](CONTRIBUTING.md)** — how to set up the dev environment, run tests, and submit PRs
+- **[Publishing](docs/PUBLISHING.md)** — how to publish releases to PyPI
+- **[Changelog](CHANGELOG.md)** — version history
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** — community standards
+
+## Author
+
+Johnatan Palacios Londoño — [johnatan.palacios@utp.edu.co](mailto:johnatan.palacios@utp.edu.co)
+
+## License
+
+[MIT](LICENSE)
+

i18n_fastapi-0.1.3/README.md

@@ -0,0 +1,76 @@
+# i18n-fastapi
+
+[![PyPI version](https://img.shields.io/pypi/v/i18n-fastapi.svg)](https://pypi.org/project/i18n-fastapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/i18n-fastapi.svg)](https://pypi.org/project/i18n-fastapi/)
+[![License](https://img.shields.io/pypi/l/i18n-fastapi.svg)](https://github.com/johnatanpalacios/i18n-fastapi/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/johnatanpalacios/i18n-fastapi/ci.yml?branch=main&label=CI)](https://github.com/johnatanpalacios/i18n-fastapi/actions)
+
+High-performance internationalization for FastAPI, powered by a Rust translation engine with automatic Python fallback.
+
+## Features
+
+- **Rust-powered engine** — blazing-fast translation lookups via PyO3, with pure Python fallback
+- **ICU plural support** — zero / one / two / few / many / other
+- **Configurable locale detection** — query params, cookies, headers, path prefix, in any priority order
+- **Plugin pattern** — one-line setup with `I18n(app)`
+- **Multiple locale directories** — shared + per-module translations with filename-based namespacing
+- **Duplicate key detection** — catch conflicts at startup, not at runtime
+- **Hot reload** — watch translation files during development
+- **Built-in endpoint** — `GET /i18n/languages` returns available locales
+- **FastAPI dependencies** — inject `Locale` and `TranslateFunc` into route handlers
+
+## Installation
+
+```bash
+pip install i18n-fastapi
+```
+
+For hot reload during development:
+
+```bash
+pip install "i18n-fastapi[reload]"
+```
+
+## Quick Start
+
+Create translation files:
+
+```
+locales/
+├── en/
+│   └── messages.json    # {"greeting": "Hello {name}"}
+└── es/
+    └── messages.json    # {"greeting": "Hola {name}"}
+```
+
+Set up your app:
+
+```python
+from fastapi import FastAPI
+from i18n_fastapi import I18n, t
+
+app = FastAPI()
+I18n(app)
+
+@app.get("/greet")
+async def greet():
+    return {"message": t("messages.greeting", name="World")}
+```
+
+Request with `?lang=es` or `Accept-Language: es` and the response adapts automatically.
+
+## Documentation
+
+- **[Usage Guide](docs/USAGE.md)** — configuration, locale detection, pluralization, and more
+- **[Contributing](CONTRIBUTING.md)** — how to set up the dev environment, run tests, and submit PRs
+- **[Publishing](docs/PUBLISHING.md)** — how to publish releases to PyPI
+- **[Changelog](CHANGELOG.md)** — version history
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** — community standards
+
+## Author
+
+Johnatan Palacios Londoño — [johnatan.palacios@utp.edu.co](mailto:johnatan.palacios@utp.edu.co)
+
+## License
+
+[MIT](LICENSE)

i18n_fastapi-0.1.3/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "i18n-fastapi"
+version = "0.1.3"
+description = "High-performance i18n for FastAPI with Rust-powered translation engine"
+authors = [{ name = "Johnatan Palacios Londoño", email = "johnatan.palacios@utp.edu.co" }]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["fastapi", "i18n", "internationalization", "rust", "translations"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Rust",
+    "Topic :: Software Development :: Internationalization",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+    "orjson>=3.9.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+reload = ["watchfiles>=0.20.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "maturin>=1.5,<2.0",
+    "pre-commit>=3.7.0",
+]
+
+[build-system]
+requires = ["maturin>=1.5,<2.0"]
+build-backend = "maturin"
+
+[tool.maturin]
+manifest-path = "rust/Cargo.toml"
+module-name = "i18n_fastapi._native"
+python-source = "python"
+features = ["pyo3/extension-module"]
+include = [{ path = "LICENSE", format = "sdist" }]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF", "ANN"]
+ignore = ["ANN401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.11"
+disallow_untyped_defs = true
+check_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

i18n_fastapi-0.1.3/python/i18n_fastapi/__init__.py

@@ -0,0 +1,15 @@
+"""i18n-fastapi: High-performance i18n for FastAPI with Rust-powered engine."""
+
+from i18n_fastapi.config import I18nConfig
+from i18n_fastapi.context import get_locale, t
+from i18n_fastapi.dependencies import Locale, TranslateFunc
+from i18n_fastapi.plugin import I18n
+
+__all__ = [
+    "I18n",
+    "I18nConfig",
+    "Locale",
+    "TranslateFunc",
+    "get_locale",
+    "t",
+]

i18n_fastapi-0.1.3/python/i18n_fastapi/_engine.py

@@ -0,0 +1,29 @@
+"""Engine selector: imports Rust native engine or falls back to pure Python."""
+
+from __future__ import annotations
+
+import logging
+import warnings
+
+logger = logging.getLogger("i18n_fastapi")
+
+RUST_AVAILABLE: bool
+
+try:
+    from i18n_fastapi._native import TranslationEngine  # type: ignore[import-not-found]
+
+    RUST_AVAILABLE = True
+except ImportError:
+    from i18n_fastapi._python_engine import (
+        TranslationEngine,  # type: ignore[assignment]
+    )
+
+    RUST_AVAILABLE = False
+    warnings.warn(
+        "i18n-fastapi: Rust engine not available, using Python fallback. "
+        "Install from a pre-compiled wheel for best performance.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+
+__all__ = ["RUST_AVAILABLE", "TranslationEngine"]

i18n_fastapi-0.1.3/python/i18n_fastapi/_python_engine.py

@@ -0,0 +1,262 @@
+"""Pure Python fallback translation engine.
+
+Provides the same interface as the Rust-native TranslationEngine.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+import orjson
+
+logger = logging.getLogger("i18n_fastapi")
+
+ICU_KEYS = frozenset({"zero", "one", "two", "few", "many", "other"})
+
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _interpolate(template: str, params: dict[str, str]) -> str:
+    if not params or "{" not in template:
+        return template
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return params.get(key, match.group(0))
+
+    return _PLACEHOLDER_RE.sub(_replace, template)
+
+
+def _select_plural(forms: dict[str, str], count: int) -> str:
+    if count == 0 and "zero" in forms:
+        return forms["zero"]
+    if count == 1 and "one" in forms:
+        return forms["one"]
+    if count == 2 and "two" in forms:
+        return forms["two"]
+    if 3 <= count <= 10 and "few" in forms:
+        return forms["few"]
+    if 11 <= count <= 99 and "many" in forms:
+        return forms["many"]
+    return forms["other"]
+
+
+def _is_plural_object(obj: dict[str, Any]) -> bool:
+    keys = set(obj.keys())
+    return "other" in keys and keys <= ICU_KEYS and len(keys) >= 2
+
+
+def _find_project_root(start_path: Path) -> Path:
+    current = start_path if start_path.is_dir() else start_path.parent
+
+    while True:
+        if (
+            (current / ".git").exists()
+            or (current / "pyproject.toml").exists()
+            or (current / "setup.py").exists()
+            or (current / "setup.cfg").exists()
+        ):
+            return current
+
+        parent = current.parent
+        if parent == current:
+            return start_path
+        current = parent
+
+
+_SKIP_DIRS = frozenset(
+    {
+        "__pycache__",
+        "venv",
+        ".venv",
+        "env",
+        "node_modules",
+        "dist",
+        "target",
+    }
+)
+
+
+def _scan_locale_dirs(root: Path, dir_name: str) -> list[Path]:
+    results: list[Path] = []
+    _scan_recursive(root, dir_name, results)
+    return results
+
+
+def _scan_recursive(directory: Path, target_name: str, results: list[Path]) -> None:
+    try:
+        entries = list(directory.iterdir())
+    except PermissionError:
+        return
+
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+
+        name = entry.name
+        if name.startswith(".") or name in _SKIP_DIRS:
+            continue
+
+        if name == target_name:
+            results.append(entry)
+        else:
+            _scan_recursive(entry, target_name, results)
+
+
+class TranslationEngine:
+    """Pure Python translation engine (fallback when Rust is unavailable)."""
+
+    def __init__(
+        self,
+        default_locale: str,
+        raise_on_duplicate: bool = True,
+        locale_dir_name: str = "locales",
+    ) -> None:
+        self.default_locale = default_locale
+        self.raise_on_duplicate = raise_on_duplicate
+        self.locale_dir_name = locale_dir_name
+        self._translations: dict[str, dict[str, Any]] = {}
+        self._loaded_dirs: list[Path] = []
+        self._missing_keys: list[tuple[str, str]] = []
+
+    def auto_discover(self, root_path: str) -> None:
+        """Auto-discover locale directories starting from root_path."""
+        root = Path(root_path)
+        project_root = _find_project_root(root)
+        dirs = _scan_locale_dirs(project_root, self.locale_dir_name)
+        for d in dirs:
+            self._load_dir(d)
+
+    def load_locale_dir(self, path: str) -> None:
+        """Load a specific locale directory."""
+        self._load_dir(Path(path))
+
+    def translate(
+        self,
+        key: str,
+        locale: str,
+        params: dict[str, str] | None = None,
+    ) -> str:
+        """Translate a key with optional parameters."""
+        if params is None:
+            params = {}
+
+        val = self._lookup(key, locale)
+
+        if val is None:
+            self._missing_keys.append((key, locale))
+            return key
+
+        if isinstance(val, dict) and _is_plural_object(val):
+            count = int(params.get("count", "0"))
+            template = _select_plural(val, count)
+            return _interpolate(template, params)
+
+        if isinstance(val, str):
+            return _interpolate(val, params)
+
+        return str(val)
+
+    def available_locales(self) -> list[str]:
+        """Return all loaded locale codes."""
+        return sorted(self._translations.keys())
+
+    def reload(self) -> None:
+        """Reload all previously loaded directories."""
+        dirs = list(self._loaded_dirs)
+        self._translations.clear()
+        self._missing_keys.clear()
+        for d in dirs:
+            self._load_dir(d)
+
+    def get_missing_keys(self) -> list[tuple[str, str]]:
+        """Return accumulated missing key lookups."""
+        return list(self._missing_keys)
+
+    def clear_missing_keys(self) -> None:
+        """Clear the missing keys log."""
+        self._missing_keys.clear()
+
+    def has_key(self, key: str, locale: str) -> bool:
+        """Check if a translation key exists for a locale."""
+        return self._lookup(key, locale) is not None
+
+    def loaded_directories(self) -> list[str]:
+        """Return loaded directory paths."""
+        return [str(p) for p in self._loaded_dirs]
+
+    def _load_dir(self, locale_dir: Path) -> None:
+        if not locale_dir.exists() or not locale_dir.is_dir():
+            return
+
+        for lang_dir in sorted(locale_dir.iterdir()):
+            if not lang_dir.is_dir():
+                continue
+
+            lang = lang_dir.name
+            lang_map = self._translations.setdefault(lang, {})
+
+            for json_file in sorted(lang_dir.rglob("*.json")):
+                relative = json_file.relative_to(lang_dir)
+                namespace = ".".join(relative.with_suffix("").parts)
+
+                try:
+                    raw = json_file.read_bytes()
+                    data = orjson.loads(raw)
+                except Exception:
+                    logger.exception("Failed to load %s", json_file)
+                    continue
+
+                self._flatten(data, namespace, lang_map, lang, str(json_file))
+
+        if locale_dir not in self._loaded_dirs:
+            self._loaded_dirs.append(locale_dir)
+
+    def _flatten(
+        self,
+        value: Any,
+        prefix: str,
+        target: dict[str, Any],
+        lang: str,
+        source_file: str,
+    ) -> None:
+        if isinstance(value, dict):
+            if _is_plural_object(value):
+                if self.raise_on_duplicate and prefix in target:
+                    msg = (
+                        f'DuplicateKeyError: Key "{prefix}" for locale '
+                        f'"{lang}" already loaded, '
+                        f'conflicting file: "{source_file}"'
+                    )
+                    raise ValueError(msg)
+                target[prefix] = {k: str(v) for k, v in value.items()}
+            else:
+                for k, v in value.items():
+                    full_key = f"{prefix}.{k}" if prefix else k
+                    self._flatten(v, full_key, target, lang, source_file)
+        elif isinstance(value, str):
+            if self.raise_on_duplicate and prefix in target:
+                msg = (
+                    f'DuplicateKeyError: Key "{prefix}" for locale '
+                    f'"{lang}" already loaded, '
+                    f'conflicting file: "{source_file}"'
+                )
+                raise ValueError(msg)
+            target[prefix] = value
+        else:
+            target[prefix] = str(value)
+
+    def _lookup(self, key: str, locale: str) -> Any | None:
+        lang_map = self._translations.get(locale)
+        if lang_map and key in lang_map:
+            return lang_map[key]
+
+        if locale != self.default_locale:
+            default_map = self._translations.get(self.default_locale)
+            if default_map and key in default_map:
+                return default_map[key]
+
+        return None

i18n_fastapi-0.1.3/python/i18n_fastapi/_watcher.py

@@ -0,0 +1,64 @@
+"""File watcher for hot-reloading translation files during development."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from i18n_fastapi._engine import TranslationEngine
+
+logger = logging.getLogger("i18n_fastapi")
+
+
+def start_watcher(engine: TranslationEngine) -> Callable[[], None]:
+    """Start a background thread that watches loaded locale dirs for changes.
+
+    Returns a stop function that terminates the watcher thread.
+    Requires the `watchfiles` package (install via `pip install i18n-fastapi[reload]`).
+    """
+    from watchfiles import watch
+
+    dirs = engine.loaded_directories()
+    if not dirs:
+        logger.warning("i18n-fastapi watcher: no directories to watch")
+        return lambda: None
+
+    stop_event = threading.Event()
+
+    def _watch_loop() -> None:
+        try:
+            for _changes in watch(
+                *dirs,
+                stop_event=stop_event,
+                watch_filter=_json_filter,
+            ):
+                logger.info("i18n-fastapi: translation files changed, reloading...")
+                try:
+                    engine.reload()
+                    logger.info("i18n-fastapi: translations reloaded")
+                except Exception:
+                    logger.exception("i18n-fastapi: failed to reload translations")
+        except Exception:
+            if not stop_event.is_set():
+                logger.exception("i18n-fastapi: watcher crashed")
+
+    thread = threading.Thread(
+        target=_watch_loop,
+        daemon=True,
+        name="i18n-fastapi-watcher",
+    )
+    thread.start()
+
+    def stop() -> None:
+        stop_event.set()
+        thread.join(timeout=2)
+
+    return stop
+
+
+def _json_filter(change: Any, path: str) -> bool:
+    """Only react to .json file changes."""
+    return path.endswith(".json")