Files
marqdo/doc/design/stdlib-i18n.md
T
cflmyandCursor a53ebb65ee Add host stdlib modules and unify view/run capabilities.
Ship fs/time/sys/json/net L1 libs (plus existing text/table), default-on host caps with soft exit under view, bilingual public/stdlib docs, and design notes for deferred math/foreign.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 10:03:54 +08:00

147 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 标准库多语言命名(草案)
| | |
|---|---|
| 状态 | **草案(先文档、后实现)** |
| 日期 | 2026-08-04 |
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
---
## 1. 要解决什么
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
---
## 2. 方案(采用)
**导入哪个库文件,就用哪套函数名。**
文件名本身表达语言;解释器只做路径解析,不做语言推断。
### 2.1 推荐:库名用目标语言书写
| 导入 | 库内函数名(示例) |
|------|-------------------|
| `> lib/text.mq.md` | `trim` · `split` · `join` |
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
| `> lib/table.mq.md` | `rows` · `row_at` |
| `> lib/表.mq.md` | `行数` · `取行` |
示例:
```markdown
---
> lib/text.mq.md
---
# main
*`xs` = > split value=a,b,c sep=,*
```
```markdown
---
> lib/文本.mq.md
---
# main
*`xs` = > 拆分 s=a,b,c sep=,*
```
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
| 导入 | 含义 |
|------|------|
| `> lib/text-en.mq.md` | 英文 API |
| `> lib/text-zh.mq.md` | 中文 API |
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
### 2.3 明确不做
| 不做 | 原因 |
|------|------|
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
| `> std/text` 再按语言展开 | 多一次魔法 |
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
---
## 2.4 特例:JSON
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
```text
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
```
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
---
## 3. 与「少而精内置」的边界
| 层 | 内容 | 如何获得 |
|----|------|----------|
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
---
## 4. 目录与扩展约定
```text
lib/
text.mq.md / 文本.mq.md
table.mq.md / 表.mq.md
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
# 暂缓:math/数学 · foreign/外联
# 其它语言:texte.mq.md / テキスト.mq.md …
```
扩展新语言时:
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
2. 库内函数名用该语言习惯。
3. 文档表增加一行映射;**无需改解释器语言开关**。
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
---
## 5. 文档与示例义务
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
---
## 6. 实现备忘(暂不开发)
实现阶段仅需:
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
---
## 7. 一句话
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**