foreignthon-docs/docs/custom-packs.md

Custom Packs

ForeignThon lets you extend or override any installed language pack locally — no PyPI account, no new package required. You can also scaffold a completely new language from scratch.

---

Local override

Create a custom.json in your project root with only the keys you want to change:

{
  "builtins": {
    "show": "print"
  },
  "keywords": {
    "when": "if"
  }
}

Then reference it in .foreignthon.toml:

[foreignthon]
lang = "es"
custom_pack = "custom.json"

Custom keys are merged on top of the installed pack. Installed pack keys are preserved — only the keys you define in custom.json are overridden.

!!! tip ForeignThon walks up the directory tree to find .foreignthon.toml, so you can place it at the project root and run fpy from any subdirectory.

---

Scaffold a new language

If no pack exists for your language yet:

fpy new myproject --lang custom

You will be prompted for:

• Language code (e.g. ru, fr, ar)
• English name (e.g. Russian)
• Native name (e.g. Русский)

This generates a custom.json based on the official template — every Python keyword, builtin, exception, and stdlib module is listed with the English value as a placeholder. Replace the keys with your language's words.

{
  "keywords": {
    "if": "if",      ← replace the key, keep the value
    "for": "for",
    "def": "def",
    ...
  }
}

The .foreignthon.toml is automatically wired to use this file.

---

Pack schema

A standalone pack must have these top-level sections:

Section	Purpose
meta	Name, code, version, authors
keywords	Python reserved words
builtins	Built-in functions
exceptions	Built-in exception classes
error_messages	Translations for bilingual error output
stdlib	Common standard library module names
postfix_keywords	English keywords to rewrite in --postfix output

Validate your pack at any time:

fpy pack custom.json
# ✓ Pack 'Russian' is valid.

---

Publishing

Once your custom.json is complete and working, you can turn it into a proper foreignthon-xx package on PyPI so others can install it with pip install foreignthon-xx.

See Contributing → Language Packs for the full guide.