From 7fe67854cd6dc4a1e0efeabd93110ab3a60a83e8 Mon Sep 17 00:00:00 2001
From: KeshavAnandCode <keshavanand.dev@gmail.com>
Date: Thu, 21 May 2026 15:14:03 +0000
Subject: [PATCH] added readme

---
 README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 118 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9bcf1fb..ba74ccd 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,118 @@
-# foreignthon-zh
+# foreignthon-zh
+
+Chinese language pack for [ForeignThon](https://foreignthon.keshavanand.net/) — write Python in 中文.
+
+---
+
+## Install
+
+```bash
+pip install foreignthon foreignthon-zh
+```
+
+---
+
+## Example
+
+**`fizzbuzz.zh.py`**
+
+```python
+定义 fizzbuzz(n):
+    对于 i 在 范围(1, n + 1):
+        如果 i % 15 == 0:
+            打印("FizzBuzz")
+        不然 i % 3 == 0:
+            打印("Fizz")
+        不然 i % 5 == 0:
+            打印("Buzz")
+        否则:
+            打印(i)
+
+fizzbuzz(20)
+```
+
+Compiles to standard Python:
+
+```python
+def fizzbuzz(n):
+    for i in range(1, n + 1):
+        if i % 15 == 0:
+            print("FizzBuzz")
+        elif i % 3 == 0:
+            print("Fizz")
+        elif i % 5 == 0:
+            print("Buzz")
+        else:
+            print(i)
+
+fizzbuzz(20)
+```
+
+Run it directly:
+
+```bash
+fpy run fizzbuzz.zh.py
+```
+
+---
+
+## Keyword reference
+
+| Python | 中文 |
+|---|---|
+| `if` | `如果` |
+| `else` | `否则` |
+| `elif` | `不然` |
+| `for` | `对于` |
+| `while` | `只要` |
+| `def` | `函数` / `定义` |
+| `class` | `类` / `类别` |
+| `return` | `返回` |
+| `import` | `导入` |
+| `from` | `从` |
+| `as` | `名` |
+| `in` | `在` |
+| `and` | `和` |
+| `or` | `或` |
+| `not` | `不` |
+| `True` | `真` |
+| `False` | `假` |
+| `None` | `空` |
+| `print` | `打印` / `写` |
+| `input` | `扫描` |
+| `len` | `长度` |
+| `range` | `范围` |
+| `lambda` | `匿名` / `λ` |
+| `yield` | `产生` |
+| `async` | `非同步` |
+| `await` | `等` |
+
+Full mapping: [`zh.json`](https://git.keshavanand.net/foreign-thon/foreignthon-zh/raw/branch/main/src/foreignthon_zh/zh.json)
+
+---
+
+## Start a project
+
+```bash
+fpy new myproject --lang zh
+cd myproject
+fpy run src/main.zh.py
+```
+
+---
+
+## Documentation
+
+→ [foreignthon.keshavanand.net](https://foreignthon.keshavanand.net/)
+
+---
+
+## Contributing
+
+Found a missing translation or a better keyword choice? Open an issue or PR — no access to the core repo needed.
+
+---
+
+## License
+
+GPL v3