# 标准库多语言命名(草案) | | | |---|---| | 状态 | **草案(先文档、后实现)** | | 日期 | 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 推荐:库名用目标语言书写 | 导入 | 库内函数名(示例) | |------|-------------------| | `import text:lib/text.mq.md` | `trim` · `split` · `join` | | `导入 文本:lib/文本.mq.md` | `去空白` · `拆分` · `拼接` | | `import table:lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) | | `导入 表:lib/表.mq.md` | `行数` · `取行` | 示例: ```markdown --- import: text: 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 可选:同概念用后缀区分(同目录、同「概念」) 若希望「同一概念」在文件名上仍共享拉丁词根,可用: | 导入 | 含义 | |------|------| | `import text-en:lib/text-en.mq.md` | 英文 API | | `import text-zh: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 # 中英文档均 `import json: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 `import …: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`——无语言开关。**