foreign-thon-old/docs/language-packs.md

Language Packs

A language pack is a JSON file that maps foreign tokens to Python equivalents, published as foreignthon-<code> on PyPI.

Available packs

Package	Language	Install
foreignthon-es	Spanish	pip install foreignthon-es
foreignthon-ta	Tamil	pip install foreignthon-ta
foreignthon-zh	Chinese	pip install foreignthon-zh

JSON schema

Every pack must have these top-level keys:

{
  "meta": {
    "name": "Spanish",
    "native_name": "Español",
    "code": "es",
    "version": "0.1.0",
    "authors": []
  },
  "keywords":      { "si": "if", "para": "for", ... },
  "builtins":      { "imprimir": "print", "rango": "range", ... },
  "exceptions":    { "ErrorDeValor": "ValueError", ... },
  "error_messages":{ "ValueError": "Error de valor", ... },
  "stdlib":        { "matematicas": "math", ... }
}

• keywords — Python reserved words (if, for, def, class …)
• builtins — built-in functions (print, range, len …)
• exceptions — built-in exception names (ValueError, TypeError …)
• error_messages — translations for bilingual error output
• stdlib — common standard library module names (math, sys …)

Third-party library names (numpy, pandas etc.) are out of scope.

Creating a pack

1. Copy packages/langs/es/ to packages/langs/<code>/
2. Rename every foreignthon_es → foreignthon_<code>
3. Fill in <code>.json following the schema above
4. Validate: fpy pack packages/langs/<code>/src/foreignthon_<code>/<code>.json
5. Install locally: pip install -e packages/langs/<code>
6. Test: fpy run myscript.<code>.py

Publishing a pack

python -m build packages/langs/<code>
twine upload packages/langs/<code>/dist/*

Anyone can publish an independent foreignthon-<code> pack — you don't need to be a core maintainer.

How discovery works

Packs register themselves via Python entry points:

# in the pack's pyproject.toml
[project.entry-points."foreignthon.langs"]
es = "foreignthon_es"

The core finds all installed packs automatically — no config needed.