docs/language-packs/index.md

@@ -1 +1,55 @@
 # Language Packs
+
+Language packs are separate PyPI packages that define keyword, builtin, and exception mappings for a specific human language. Each is installed independently and discovered automatically by ForeignThon.
+
+---
+
+## Install a pack
+
+```bash
+pip install foreignthon-<code>
+```
+
+Multiple packs can coexist — install as many as you need.
+
+---
+
+## Available packs
+
+| Language | Code | Install |
+|---|---|---|
+| Spanish | `es` | `pip install foreignthon-es` |
+| Tamil | `ta` | `pip install foreignthon-ta` |
+
+---
+
+## How discovery works
+
+ForeignThon uses Python [entry points](https://packaging.python.org/en/latest/specifications/entry-points/) to discover installed packs. Installing a pack is sufficient — no configuration required.
+
+```toml
+# Each pack registers itself in its pyproject.toml:
+[project.entry-points."foreignthon.langs"]
+es = "foreignthon_es"
+```
+
+---
+
+## What a pack covers
+
+| Section | Examples |
+|---|---|
+| Keywords | `if`, `for`, `def`, `class`, `return` … |
+| Builtins | `print`, `range`, `len`, `type` … |
+| Exceptions | `ValueError`, `TypeError`, `KeyError` … |
+| Error messages | Bilingual error output translations |
+| Stdlib | `math`, `sys`, `os`, `random` … |
+| Postfix keywords | Which keywords to rewrite with `@@` on decompile |
+
+Third-party library names (numpy, pandas, etc.) are intentionally out of scope.
+
+---
+
+## Don't see your language?
+
+Anyone can publish a `foreignthon-xx` pack — no core access required. See [Contributing → Language Packs](../contributing/language-packs.md) to get started, or use a [local custom pack](../custom-packs.md) in the meantime.