polyglot-python 0.2.0__py3-none-any.whl

polyglot_python/__init__.py

@@ -0,0 +1,24 @@
+"""polyglot-python: deterministic multilingual Python keyword transpiler."""
+
+from .translator import (
+    Locale,
+    LocaleError,
+    TokenizeFailure,
+    Translation,
+    load_locales,
+    resolve_locale,
+    translate,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Locale",
+    "LocaleError",
+    "TokenizeFailure",
+    "Translation",
+    "__version__",
+    "load_locales",
+    "resolve_locale",
+    "translate",
+]

polyglot_python/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

polyglot_python/cli.py

@@ -0,0 +1,225 @@
+"""Command line interface for polyglot-python."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import traceback
+from types import CodeType
+from typing import Sequence
+
+from . import __version__
+from .translator import (
+    Locale,
+    TokenizeFailure,
+    Translation,
+    load_locales,
+    resolve_locale,
+    translate,
+)
+
+
+class _Failure(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+def _configure_console() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", newline="\n")
+        except (ValueError, OSError):
+            pass
+
+
+def _message(locale: Locale | None, key: str, fallback: str) -> str:
+    if locale is None:
+        return fallback
+    return locale.messages.get(key, fallback)
+
+
+def _read_source(path: str) -> str:
+    try:
+        with open(path, "r", encoding="utf-8-sig", newline="") as handle:
+            return handle.read()
+    except UnicodeDecodeError as exc:
+        raise _Failure(
+            f"cannot decode {path} as UTF-8: {exc.reason} at byte {exc.start}"
+        ) from exc
+    except OSError as exc:
+        reason = exc.strerror or str(exc)
+        raise _Failure(f"cannot read {path}: {reason}") from exc
+
+
+def _prepare(path: str, lang: str | None) -> tuple[Locale | None, Translation]:
+    text = _read_source(path)
+    code = resolve_locale(lang, text, path)
+    locale: Locale | None = None
+    if code is not None:
+        locales = load_locales()
+        locale = locales.get(code)
+        if locale is None:
+            available = ", ".join(sorted(locales))
+            raise _Failure(f"unknown locale {code!r}; available: {available}")
+    try:
+        translation = translate(text, locale)
+    except TokenizeFailure as exc:
+        prefix = _message(locale, "token_error", "Tokenization error")
+        raise _Failure(
+            f"{prefix}: {path}:{exc.line}:{exc.column}: {exc.detail}"
+        ) from exc
+    return locale, translation
+
+
+def _compile(
+    path: str, locale: Locale | None, translation: Translation
+) -> CodeType | None:
+    try:
+        return compile(translation.python, path, "exec")
+    except SyntaxError as exc:
+        lineno = exc.lineno or 1
+        column = translation.original_column(lineno, exc.offset or 1)
+        prefix = _message(locale, "syntax_error", "Syntax error")
+        print(
+            f"{prefix}: {path}:{lineno}:{column}: {exc.msg}",
+            file=sys.stderr,
+        )
+        return None
+
+
+def _run(namespace: argparse.Namespace) -> int:
+    try:
+        locale, translation = _prepare(namespace.file, namespace.lang)
+    except _Failure as exc:
+        print(f"polyglot-python: {exc.message}", file=sys.stderr)
+        return 1
+
+    code = _compile(namespace.file, locale, translation)
+    if code is None:
+        return 1
+
+    scope = {
+        "__name__": "__main__",
+        "__file__": os.path.abspath(namespace.file),
+    }
+    saved_argv = sys.argv
+    sys.argv = [namespace.file, *namespace.args]
+    try:
+        exec(code, scope)
+    except SystemExit as exc:
+        if exc.code is None:
+            return 0
+        if isinstance(exc.code, int):
+            return exc.code
+        print(exc.code, file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        raise
+    except Exception:
+        prefix = _message(locale, "runtime_error", "Runtime error")
+        print(f"{prefix}: {namespace.file}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+    finally:
+        sys.argv = saved_argv
+    return 0
+
+
+def _check(namespace: argparse.Namespace) -> int:
+    try:
+        locale, translation = _prepare(namespace.file, namespace.lang)
+    except _Failure as exc:
+        print(f"polyglot-python: {exc.message}", file=sys.stderr)
+        return 1
+    return 0 if _compile(namespace.file, locale, translation) is not None else 1
+
+
+def _translate(namespace: argparse.Namespace) -> int:
+    try:
+        _, translation = _prepare(namespace.file, namespace.lang)
+    except _Failure as exc:
+        print(f"polyglot-python: {exc.message}", file=sys.stderr)
+        return 1
+
+    if namespace.output:
+        try:
+            with open(namespace.output, "w", encoding="utf-8", newline="") as handle:
+                handle.write(translation.python)
+        except OSError as exc:
+            reason = exc.strerror or str(exc)
+            print(
+                f"polyglot-python: cannot write {namespace.output}: {reason}",
+                file=sys.stderr,
+            )
+            return 1
+    else:
+        sys.stdout.write(translation.python)
+    return 0
+
+
+def _locales(_namespace: argparse.Namespace) -> int:
+    locales = load_locales()
+    print(f"{'code':<6}{'name':<16}keywords")
+    for code in sorted(locales):
+        locale = locales[code]
+        print(f"{code:<6}{locale.name:<16}{len(locale.keywords)}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="polyglot-python",
+        description="Write Python in your own language: deterministic keyword translation.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"polyglot-python {__version__}"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run = subparsers.add_parser("run", help="translate and execute a program")
+    run.add_argument("file", help="localized source file")
+    run.add_argument("--lang", metavar="CODE", help="locale code, e.g. tr")
+    run.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="arguments passed to the program",
+    )
+    run.set_defaults(handler=_run)
+
+    transform = subparsers.add_parser(
+        "translate", help="print the Python translation"
+    )
+    transform.add_argument("file", help="localized source file")
+    transform.add_argument("--lang", metavar="CODE", help="locale code, e.g. tr")
+    transform.add_argument(
+        "-o", "--output", metavar="PATH", help="write the translation to PATH"
+    )
+    transform.set_defaults(handler=_translate)
+
+    check = subparsers.add_parser(
+        "check", help="translate and compile a program without running it"
+    )
+    check.add_argument("file", help="localized source file")
+    check.add_argument("--lang", metavar="CODE", help="locale code, e.g. tr")
+    check.set_defaults(handler=_check)
+
+    listing = subparsers.add_parser("locales", help="list bundled locales")
+    listing.set_defaults(handler=_locales)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    _configure_console()
+    parser = build_parser()
+    namespace = parser.parse_args(argv)
+    return namespace.handler(namespace)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

polyglot_python/locales.json

@@ -0,0 +1,410 @@
+{
+  "version": 1,
+  "locales": {
+    "tr": {
+      "name": "Türkçe",
+      "keywords": {
+        "False": "Yanlış",
+        "None": "Hiçbiri",
+        "True": "Doğru",
+        "and": "ve",
+        "as": "olarak",
+        "assert": "doğrula",
+        "async": "eşzamansız",
+        "await": "bekle",
+        "break": "kır",
+        "class": "sınıf",
+        "continue": "sürdür",
+        "def": "fonksiyon",
+        "del": "sil",
+        "elif": "değilse_eğer",
+        "else": "değilse",
+        "except": "yakala",
+        "finally": "sonunda",
+        "for": "için",
+        "from": "dan",
+        "global": "global",
+        "if": "eğer",
+        "import": "içe_aktar",
+        "in": "içinde",
+        "is": "aynı",
+        "lambda": "lambda",
+        "nonlocal": "dış",
+        "not": "değil",
+        "or": "veya",
+        "pass": "geç",
+        "raise": "yükselt",
+        "return": "döndür",
+        "try": "dene",
+        "while": "iken",
+        "with": "ile",
+        "yield": "üret"
+      },
+      "messages": {
+        "syntax_error": "Sözdizimi hatası",
+        "runtime_error": "Çalışma zamanı hatası",
+        "token_error": "Belirteç hatası"
+      }
+    },
+    "es": {
+      "name": "Español",
+      "keywords": {
+        "False": "Falso",
+        "None": "Ninguno",
+        "True": "Verdadero",
+        "and": "y",
+        "as": "como",
+        "assert": "afirmar",
+        "async": "asíncrono",
+        "await": "esperar",
+        "break": "romper",
+        "class": "clase",
+        "continue": "continuar",
+        "def": "función",
+        "del": "eliminar",
+        "elif": "sino_si",
+        "else": "sino",
+        "except": "excepto",
+        "finally": "finalmente",
+        "for": "para",
+        "from": "desde",
+        "global": "global",
+        "if": "si",
+        "import": "importar",
+        "in": "en",
+        "is": "es",
+        "lambda": "lambda",
+        "nonlocal": "no_local",
+        "not": "no",
+        "or": "o",
+        "pass": "pasar",
+        "raise": "lanzar",
+        "return": "devolver",
+        "try": "intentar",
+        "while": "mientras",
+        "with": "con",
+        "yield": "generar"
+      },
+      "messages": {
+        "syntax_error": "Error de sintaxis",
+        "runtime_error": "Error en tiempo de ejecución",
+        "token_error": "Error de tokenización"
+      }
+    },
+    "pt": {
+      "name": "Português",
+      "keywords": {
+        "False": "Falso",
+        "None": "Nenhum",
+        "True": "Verdadeiro",
+        "and": "e",
+        "as": "como",
+        "assert": "afirmar",
+        "async": "assíncrono",
+        "await": "aguardar",
+        "break": "quebrar",
+        "class": "classe",
+        "continue": "continuar",
+        "def": "função",
+        "del": "apagar",
+        "elif": "senão_se",
+        "else": "senão",
+        "except": "exceto",
+        "finally": "finalmente",
+        "for": "para",
+        "from": "de",
+        "global": "global",
+        "if": "se",
+        "import": "importar",
+        "in": "em",
+        "is": "é",
+        "lambda": "lambda",
+        "nonlocal": "não_local",
+        "not": "não",
+        "or": "ou",
+        "pass": "passar",
+        "raise": "levantar",
+        "return": "retornar",
+        "try": "tentar",
+        "while": "enquanto",
+        "with": "com",
+        "yield": "gerar"
+      },
+      "messages": {
+        "syntax_error": "Erro de sintaxe",
+        "runtime_error": "Erro de execução",
+        "token_error": "Erro de tokenização"
+      }
+    },
+    "de": {
+      "name": "Deutsch",
+      "keywords": {
+        "False": "Falsch",
+        "None": "Nichts",
+        "True": "Wahr",
+        "and": "und",
+        "as": "als",
+        "assert": "behaupten",
+        "async": "asynchron",
+        "await": "warten",
+        "break": "abbrechen",
+        "class": "klasse",
+        "continue": "fortsetzen",
+        "def": "funktion",
+        "del": "löschen",
+        "elif": "sonst_wenn",
+        "else": "sonst",
+        "except": "außer",
+        "finally": "schließlich",
+        "for": "für",
+        "from": "von",
+        "global": "global",
+        "if": "wenn",
+        "import": "importieren",
+        "in": "in",
+        "is": "ist",
+        "lambda": "lambda",
+        "nonlocal": "nichtlokal",
+        "not": "nicht",
+        "or": "oder",
+        "pass": "passieren",
+        "raise": "auslösen",
+        "return": "zurückgeben",
+        "try": "versuchen",
+        "while": "solange",
+        "with": "mit",
+        "yield": "erzeugen"
+      },
+      "messages": {
+        "syntax_error": "Syntaxfehler",
+        "runtime_error": "Laufzeitfehler",
+        "token_error": "Tokenisierungsfehler"
+      }
+    },
+    "fr": {
+      "name": "Français",
+      "keywords": {
+        "False": "Faux",
+        "None": "Aucun",
+        "True": "Vrai",
+        "and": "et",
+        "as": "comme",
+        "assert": "affirmer",
+        "async": "asynchrone",
+        "await": "attendre",
+        "break": "casser",
+        "class": "classe",
+        "continue": "continuer",
+        "def": "fonction",
+        "del": "supprimer",
+        "elif": "sinon_si",
+        "else": "sinon",
+        "except": "excepté",
+        "finally": "finalement",
+        "for": "pour",
+        "from": "depuis",
+        "global": "global",
+        "if": "si",
+        "import": "importer",
+        "in": "dans",
+        "is": "est",
+        "lambda": "lambda",
+        "nonlocal": "non_local",
+        "not": "non",
+        "or": "ou",
+        "pass": "passer",
+        "raise": "lever",
+        "return": "retourner",
+        "try": "essayer",
+        "while": "tant_que",
+        "with": "avec",
+        "yield": "générer"
+      },
+      "messages": {
+        "syntax_error": "Erreur de syntaxe",
+        "runtime_error": "Erreur d'exécution",
+        "token_error": "Erreur de tokenisation"
+      }
+    },
+    "zh": {
+      "name": "中文",
+      "keywords": {
+        "False": "假",
+        "None": "空",
+        "True": "真",
+        "and": "并且",
+        "as": "作为",
+        "assert": "断言",
+        "async": "异步",
+        "await": "等待",
+        "break": "跳出",
+        "class": "类",
+        "continue": "继续",
+        "def": "函数",
+        "del": "删除",
+        "elif": "否则如果",
+        "else": "否则",
+        "except": "捕获",
+        "finally": "最终",
+        "for": "对于",
+        "from": "从",
+        "global": "全局",
+        "if": "如果",
+        "import": "导入",
+        "in": "在",
+        "is": "是",
+        "lambda": "匿名",
+        "nonlocal": "非局部",
+        "not": "不是",
+        "or": "或者",
+        "pass": "跳过",
+        "raise": "抛出",
+        "return": "返回",
+        "try": "尝试",
+        "while": "当",
+        "with": "使用",
+        "yield": "产出"
+      },
+      "messages": {
+        "syntax_error": "语法错误",
+        "runtime_error": "运行时错误",
+        "token_error": "分词错误"
+      }
+    },
+    "hi": {
+      "name": "हिन्दी",
+      "keywords": {
+        "False": "गलत",
+        "None": "कुछ_नहीं",
+        "True": "सही",
+        "and": "और",
+        "as": "के_रूप_में",
+        "assert": "दावा",
+        "async": "अतुल्यकालिक",
+        "await": "प्रतीक्षा",
+        "break": "तोड़ो",
+        "class": "वर्ग",
+        "continue": "जारी_रखो",
+        "def": "फलन",
+        "del": "हटाओ",
+        "elif": "अन्यथा_अगर",
+        "else": "अन्यथा",
+        "except": "पकड़ो",
+        "finally": "अंततः",
+        "for": "के_लिए",
+        "from": "से",
+        "global": "वैश्विक",
+        "if": "अगर",
+        "import": "आयात",
+        "in": "में",
+        "is": "है",
+        "lambda": "लैम्ब्डा",
+        "nonlocal": "स्थानीय_नहीं",
+        "not": "नहीं",
+        "or": "या",
+        "pass": "छोड़ो",
+        "raise": "उठाओ",
+        "return": "लौटाओ",
+        "try": "प्रयास",
+        "while": "जबकि",
+        "with": "के_साथ",
+        "yield": "उत्पन्न"
+      },
+      "messages": {
+        "syntax_error": "वाक्यविन्यास त्रुटि",
+        "runtime_error": "रनटाइम त्रुटि",
+        "token_error": "टोकन त्रुटि"
+      }
+    },
+    "ar": {
+      "name": "العربية",
+      "keywords": {
+        "False": "خطأ",
+        "None": "لا_شيء",
+        "True": "صحيح",
+        "and": "و",
+        "as": "بصفة",
+        "assert": "أكد",
+        "async": "غير_متزامن",
+        "await": "انتظر",
+        "break": "اكسر",
+        "class": "صنف",
+        "continue": "تابع",
+        "def": "دالة",
+        "del": "احذف",
+        "elif": "وإلا_إذا",
+        "else": "وإلا",
+        "except": "التقط",
+        "finally": "أخيرا",
+        "for": "لكل",
+        "from": "من",
+        "global": "عام",
+        "if": "إذا",
+        "import": "استورد",
+        "in": "في",
+        "is": "هو",
+        "lambda": "لامبدا",
+        "nonlocal": "غير_محلي",
+        "not": "ليس",
+        "or": "أو",
+        "pass": "مرر",
+        "raise": "ارفع",
+        "return": "إرجاع",
+        "try": "حاول",
+        "while": "بينما",
+        "with": "مع",
+        "yield": "أنتج"
+      },
+      "messages": {
+        "syntax_error": "خطأ في الصياغة",
+        "runtime_error": "خطأ في وقت التشغيل",
+        "token_error": "خطأ في الترميز"
+      }
+    },
+    "ru": {
+      "name": "Русский",
+      "keywords": {
+        "False": "Ложь",
+        "None": "Ничто",
+        "True": "Истина",
+        "and": "и",
+        "as": "как",
+        "assert": "утверждать",
+        "async": "асинхронный",
+        "await": "ожидать",
+        "break": "прервать",
+        "class": "класс",
+        "continue": "продолжить",
+        "def": "определить",
+        "del": "удалить",
+        "elif": "иначе_если",
+        "else": "иначе",
+        "except": "исключение",
+        "finally": "наконец",
+        "for": "для",
+        "from": "из",
+        "global": "глобальный",
+        "if": "если",
+        "import": "импорт",
+        "in": "в",
+        "is": "это",
+        "lambda": "лямбда",
+        "nonlocal": "нелокальный",
+        "not": "не",
+        "or": "или",
+        "pass": "пропустить",
+        "raise": "поднять",
+        "return": "вернуть",
+        "try": "попробовать",
+        "while": "пока",
+        "with": "с",
+        "yield": "генерировать"
+      },
+      "messages": {
+        "syntax_error": "Синтаксическая ошибка",
+        "runtime_error": "Ошибка выполнения",
+        "token_error": "Ошибка токенизации"
+      }
+    }
+  }
+}

polyglot_python/translator.py

@@ -0,0 +1,284 @@
+"""Deterministic translation of localized Python keywords.
+
+Only exact ``NAME`` tokens that match a locale keyword are rewritten; strings,
+comments, f-strings, numbers and attribute names are never touched. Line
+numbers are preserved exactly, and a per-line column map lets callers report
+positions against the original localized source.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import keyword
+import re
+import tokenize
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from types import MappingProxyType
+from typing import Mapping
+
+_SUFFIX_LOCALES = {
+    ".tr": "tr",
+    ".es": "es",
+    ".pt": "pt",
+    ".de": "de",
+    ".fr": "fr",
+    ".zh": "zh",
+    ".hi": "hi",
+    ".ar": "ar",
+    ".ru": "ru",
+}
+
+_DIRECTIVE = re.compile(r"^#\s*polyglot-python:\s*([A-Za-z][A-Za-z0-9_-]*)\s*$")
+
+_MESSAGE_KEYS = (
+    "syntax_error",
+    "runtime_error",
+    "token_error",
+)
+
+_SIGNIFICANT = (tokenize.NAME, tokenize.OP, tokenize.NUMBER, tokenize.STRING)
+
+
+class PolyglotError(Exception):
+    """Base class for all polyglot-python errors."""
+
+
+class LocaleError(PolyglotError):
+    """Raised when locale data is malformed or a locale is unknown."""
+
+
+class TokenizeFailure(PolyglotError):
+    """Raised when the localized source cannot be tokenized."""
+
+    def __init__(self, line: int, column: int, detail: str) -> None:
+        super().__init__(detail)
+        self.line = line
+        self.column = column
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class Locale:
+    """A validated locale: Python keyword -> localized keyword."""
+
+    code: str
+    name: str
+    keywords: Mapping[str, str]
+    messages: Mapping[str, str]
+
+    @property
+    def reverse_keywords(self) -> dict[str, str]:
+        return {local: python for python, local in self.keywords.items()}
+
+
+@dataclass(frozen=True)
+class Translation:
+    """A translated program plus its original-source column maps."""
+
+    original: str
+    python: str
+    column_maps: tuple[tuple[int, ...], ...]
+
+    def original_column(self, lineno: int, offset: int) -> int:
+        """Map a 1-based translated column back to a 1-based original column.
+
+        An empty map means the line was not touched, so the column is already
+        correct. Out-of-range positions are clamped to the line bounds.
+        """
+        if not self.column_maps or lineno < 1:
+            return offset
+        index = min(lineno, len(self.column_maps)) - 1
+        column_map = self.column_maps[index]
+        if not column_map:
+            return offset
+        position = min(max(offset, 1), len(column_map)) - 1
+        return column_map[position] + 1
+
+
+def _tokenizes_as_name(word: str) -> bool:
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(word).readline))
+    except (tokenize.TokenError, IndentationError):
+        return False
+    significant = [
+        token
+        for token in tokens
+        if token.type not in (tokenize.ENDMARKER, tokenize.NEWLINE, tokenize.NL)
+    ]
+    return (
+        len(significant) == 1
+        and significant[0].type == tokenize.NAME
+        and significant[0].string == word
+    )
+
+
+def _validate_keywords(code: str, raw: object) -> Mapping[str, str]:
+    if not isinstance(raw, dict):
+        raise LocaleError(f"{code}: keywords must be a JSON object")
+    expected = set(keyword.kwlist)
+    actual = set(raw)
+    if actual != expected:
+        missing = sorted(expected - actual)
+        extra = sorted(actual - expected)
+        raise LocaleError(
+            f"{code}: keywords must match Python keywords exactly "
+            f"(missing={missing}, extra={extra})"
+        )
+    seen: dict[str, str] = {}
+    for python_word in keyword.kwlist:
+        local = raw[python_word]
+        if not isinstance(local, str) or not local.isidentifier():
+            raise LocaleError(
+                f"{code}: {python_word!r} maps to an invalid identifier: {local!r}"
+            )
+        if keyword.iskeyword(local) and local != python_word:
+            raise LocaleError(
+                f"{code}: {python_word!r} maps to reserved Python keyword {local!r}"
+            )
+        if local in seen:
+            raise LocaleError(
+                f"{code}: duplicate localized keyword {local!r} "
+                f"for {seen[local]!r} and {python_word!r}"
+            )
+        if not _tokenizes_as_name(local):
+            raise LocaleError(
+                f"{code}: {python_word!r} maps to {local!r}, which this "
+                "interpreter does not tokenize as one identifier "
+                "(Python 3.12+ is required for Indic scripts)"
+            )
+        seen[local] = python_word
+    return MappingProxyType(dict(raw))
+
+
+def _validate_messages(code: str, raw: object) -> Mapping[str, str]:
+    if not isinstance(raw, dict):
+        raise LocaleError(f"{code}: messages must be a JSON object")
+    messages: dict[str, str] = {}
+    for key in _MESSAGE_KEYS:
+        value = raw.get(key)
+        if not isinstance(value, str) or not value:
+            raise LocaleError(f"{code}: missing message {key!r}")
+        messages[key] = value
+    return MappingProxyType(messages)
+
+
+@lru_cache(maxsize=1)
+def load_locales() -> Mapping[str, Locale]:
+    """Load and validate every bundled locale."""
+    raw_text = resources.files("polyglot_python").joinpath("locales.json").read_text(
+        encoding="utf-8"
+    )
+    return _parse_locales(raw_text)
+
+
+def _parse_locales(raw_text: str) -> Mapping[str, Locale]:
+    data = json.loads(raw_text)
+    if not isinstance(data, dict) or not isinstance(data.get("locales"), dict):
+        raise LocaleError("locales.json: expected an object with a 'locales' object")
+    locales: dict[str, Locale] = {}
+    for code, entry in data["locales"].items():
+        if not isinstance(entry, dict):
+            raise LocaleError(f"{code}: locale entry must be a JSON object")
+        name = entry.get("name")
+        if not isinstance(name, str) or not name:
+            raise LocaleError(f"{code}: missing locale name")
+        locales[code] = Locale(
+            code=code,
+            name=name,
+            keywords=_validate_keywords(code, entry.get("keywords")),
+            messages=_validate_messages(code, entry.get("messages")),
+        )
+    return MappingProxyType(locales)
+
+
+def resolve_locale(
+    explicit: str | None, text: str, filename: str | None = None
+) -> str | None:
+    """Resolve a locale code: --lang, then ``# polyglot-python: xx``, then suffix."""
+    if explicit:
+        return explicit.strip().lower()
+    first_line = text.split("\n", 1)[0].strip()
+    match = _DIRECTIVE.match(first_line)
+    if match:
+        return match.group(1).lower()
+    if filename:
+        suffix = Path(filename).suffix.lower()
+        if suffix in _SUFFIX_LOCALES:
+            return _SUFFIX_LOCALES[suffix]
+    return None
+
+
+def translate(text: str, locale: Locale | None) -> Translation:
+    """Translate localized keywords to Python keywords, deterministically."""
+    original = text
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    if locale is None:
+        return Translation(
+            original=original,
+            python=normalized,
+            column_maps=tuple(() for _ in normalized.split("\n")),
+        )
+
+    reverse = locale.reverse_keywords
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(normalized).readline))
+    except tokenize.TokenError as exc:
+        detail = str(exc.args[0]) if exc.args else "tokenization failed"
+        position = exc.args[1] if len(exc.args) > 1 else (1, 0)
+        raise TokenizeFailure(
+            int(position[0]), int(position[1]) + 1, detail
+        ) from exc
+    except IndentationError as exc:
+        raise TokenizeFailure(exc.lineno or 1, exc.offset or 1, str(exc)) from exc
+
+    replacements: dict[int, list[tuple[int, int, str]]] = {}
+    previous: tokenize.TokenInfo | None = None
+    for token in tokens:
+        after_dot = (
+            previous is not None
+            and previous.type == tokenize.OP
+            and previous.string == "."
+        )
+        if (
+            token.type == tokenize.NAME
+            and not after_dot
+            and token.string in reverse
+        ):
+            row, column = token.start
+            replacements.setdefault(row, []).append(
+                (column, token.end[1], reverse[token.string])
+            )
+        if token.type in _SIGNIFICANT:
+            previous = token
+
+    out_lines: list[str] = []
+    column_maps: list[tuple[int, ...]] = []
+    for lineno, line in enumerate(normalized.split("\n"), 1):
+        edits = sorted(replacements.get(lineno, ()))
+        if not edits:
+            out_lines.append(line)
+            column_maps.append(())
+            continue
+        parts: list[str] = []
+        column_map: list[int] = []
+        position = 0
+        for start, end, replacement in edits:
+            parts.append(line[position:start])
+            column_map.extend(range(position, start))
+            parts.append(replacement)
+            column_map.extend([start] * len(replacement))
+            position = end
+        parts.append(line[position:])
+        column_map.extend(range(position, len(line)))
+        out_lines.append("".join(parts))
+        column_maps.append(tuple(column_map))
+
+    return Translation(
+        original=original,
+        python="\n".join(out_lines),
+        column_maps=tuple(column_maps),
+    )

polyglot_python-0.2.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: polyglot-python
+Version: 0.2.0
+Summary: Deterministic multilingual Python keyword transpiler: write Python in your own language.
+Author: Furox-Art
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Furox-Art/polyglot-python
+Project-URL: Issues, https://github.com/Furox-Art/polyglot-python/issues
+Project-URL: Changelog, https://github.com/Furox-Art/polyglot-python/blob/main/CHANGELOG.md
+Keywords: python,transpiler,localization,multilingual,deterministic
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# polyglot-python
+
+Write Python in your own language, deterministically.
+
+polyglot-python is a keyword transpiler for Python. You keep Python's grammar and write
+programs with localized keywords; polyglot-python maps those keywords to the real Python
+keywords and hands the result to CPython. No AI, no network, no randomness:
+the same source, locale and version always produce byte-identical Python.
+
+It is not a prose-to-code translator and it does not guess intent. It is Python
+syntax with your words.
+
+## Install
+
+```bash
+pip install polyglot-python   # after the first release
+pip install -e .              # from source
+```
+
+The first release is prepared but not yet on PyPI; install from source until it
+is published. Requires Python 3.12+. Python 3.10/3.11 are not supported because
+their tokenizer splits Indic combining marks, so several Hindi keywords would
+not translate. No runtime dependencies.
+
+## Quick start
+
+`examples/classify.tr`:
+
+```python
+fonksiyon classify(n):
+    eğer n % 15 == 0:
+        döndür "FizzBuzz"
+    değilse_eğer n % 3 == 0:
+        döndür "Fizz"
+    değilse_eğer n % 5 == 0:
+        döndür "Buzz"
+    değilse:
+        döndür str(n)
+
+için n içinde range(1, 16):
+    print(classify(n))
+```
+
+```bash
+polyglot-python run examples/classify.tr
+polyglot-python check examples/classify.tr
+polyglot-python translate examples/classify.tr
+polyglot-python translate examples/classify.tr -o classify.py
+```
+
+The same FizzBuzz program is included for every locale under `examples/`.
+
+## Locales
+
+| Code | Language   | `if`     | `def`       | `return`  |
+|------|------------|----------|-------------|-----------|
+| tr   | Türkçe     | `eğer`   | `fonksiyon` | `döndür`  |
+| es   | Español    | `si`     | `función`   | `devolver`|
+| pt   | Português  | `se`     | `função`    | `retornar`|
+| de   | Deutsch    | `wenn`   | `funktion`  | `zurückgeben` |
+| fr   | Français   | `si`     | `fonction`  | `retourner` |
+| zh   | 中文        | `如果`   | `函数`      | `返回`    |
+| hi   | हिन्दी      | `अगर`    | `फलन`       | `लौटाओ`   |
+| ar   | العربية    | `إذا`    | `دالة`      | `إرجاع`   |
+| ru   | Русский    | `если`   | `определить`| `вернуть` |
+
+`polyglot-python locales` prints the full list. Every locale defines exactly the 35
+Python hard keywords (`keyword.kwlist`); soft keywords such as `match`, `case`
+and `type` stay English.
+
+Locale selection order:
+
+1. `--lang CODE`
+2. first line directive: `# polyglot-python: tr`
+3. file suffix: `.tr`, `.es`, `.pt`, `.de`, `.fr`, `.zh`, `.hi`, `.ar`, `.ru`
+
+## CLI
+
+```text
+polyglot-python run FILE [--lang CODE] [args...]
+polyglot-python check FILE [--lang CODE]
+polyglot-python translate FILE [--lang CODE] [-o OUT]
+polyglot-python locales
+polyglot-python --version
+```
+
+For `run`, place options before `FILE`; everything after `FILE` is passed to the
+program as `sys.argv[1:]`.
+
+## Guarantees
+
+- Only exact `NAME` tokens that match a locale keyword are rewritten. Strings,
+  comments, f-strings, numbers, identifiers and attribute names are untouched.
+- Line numbers are preserved one-to-one; a per-line column map translates
+  reported error positions back to the localized source.
+- `translate -o` and stdout output are UTF-8 with LF line endings on every
+  platform, so exports are byte-identical and re-verifiable.
+- `check` translates and compiles without executing the program, so localized
+  sources can be validated safely.
+- A localized keyword after a dot is treated as an attribute name and never
+  rewritten.
+- Localized keywords are reserved words in their locale.
+- Missing files, invalid UTF-8, unknown locales and untokenizable input fail
+  with a clear message; nothing is guessed or silently skipped.
+- Error headers are localized; CPython's detail text (for example
+  `ZeroDivisionError`) remains English for now.
+- Exit codes from the executed program are propagated.
+
+## Limits
+
+- Phase 1 localizes keywords only: no localization of builtins (`print`,
+  `range`, ...), the standard library, or English exception text.
+- This is not a natural-language compiler. It does not understand Spanish or
+  Turkish prose; it understands Python syntax written with localized keywords.
+- The local prototype ships 9 locales. Other languages can be added by editing
+  `src/polyglot_python/locales.json`; malformed tables are rejected at load time.
+- Tested on CPython 3.12 on Windows; CI covers 3.12-3.14 on Linux and 3.12
+  on Windows and macOS. The code targets 3.12+.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"
+.venv/Scripts/python -m pytest -q --cov=polyglot_python --cov-fail-under=100
+```
+
+The suite contains 119 tests with 100% statement coverage, including every
+keyword in both directions for all 9 locales, end-to-end CLI runs of every
+example, version consistency with the changelog, and byte-level determinism
+checks. CI runs Ubuntu 3.12-3.14 plus Windows and macOS at 3.12, enforces the
+100% coverage gate on Linux 3.12, translates every example twice on all three
+operating systems to compare bytes and line counts, and builds the wheel,
+installs it into a clean environment, and smoke-tests it. Dependabot keeps
+GitHub Actions and development dependencies current. A separate release
+workflow publishes tagged GitHub Releases to PyPI through Trusted Publishing.
+
+## Releasing
+
+Publishing uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+and stores no API token.
+
+1. On PyPI, add a pending publisher for project `polyglot-python`: owner
+   `Furox-Art`, repository `polyglot-python`, workflow `release.yml`,
+   environment `pypi`.
+2. Change `version` in `pyproject.toml` and
+   `src/polyglot_python/__init__.py` together; the test suite rejects drift.
+3. Publish a GitHub Release with tag `v<version>`. The release workflow verifies
+   the tag, builds the sdist and wheel, and uploads them to PyPI.
+
+## License
+
+MIT

polyglot_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+polyglot_python/__init__.py,sha256=Ya4xPYS4dgX6dnB-vEdNpmPz26NaVnBVGZBRmyIF1f4,417
+polyglot_python/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+polyglot_python/cli.py,sha256=J3KzlL5rDe3JDDXJe0LEgfczEEHXV95w0yxlrOQ10Ow,6906
+polyglot_python/locales.json,sha256=jUMWGLZYG_BSEfKTevkJ1HS7LkZNDL2wjHfufLVyGkA,11356
+polyglot_python/translator.py,sha256=608uk99H70f83qJ0Lhbp2F7covS6BsIB70UfSqJNGao,9455
+polyglot_python-0.2.0.dist-info/licenses/LICENSE,sha256=GIA7odPA7v0zSqQfgBW_YoyTsNu058_DxugfvrwRoiM,1066
+polyglot_python-0.2.0.dist-info/METADATA,sha256=9et5Xt-QeGkKmOtDkP1JWevZH6LAMaQD-27pEFbwk9s,7020
+polyglot_python-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+polyglot_python-0.2.0.dist-info/entry_points.txt,sha256=Ovsh-hpTr6d0kZX8woBOJR9F5JStN12irNBomgvA_q4,61
+polyglot_python-0.2.0.dist-info/top_level.txt,sha256=gEuO6xZPIIHdeSV92QIEWohn5QJCug2Jilw4x7ldF9E,16
+polyglot_python-0.2.0.dist-info/RECORD,,

polyglot_python-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polyglot_python-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+polyglot-python = polyglot_python.cli:main

polyglot_python-0.2.0.dist-info/licenses/LICENSE

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

polyglot_python-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polyglot_python