## 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:

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

Then reference it in `.foreignthon.toml`:

```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:

```bash
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.

```json
{
  "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:

```bash
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](contributing/language-packs.md) for the full guide.