Files
marqdo/doc/design/stdlib-i18n.md
T
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00

5.2 KiB
Raw Blame History

标准库多语言命名(草案)

状态 草案(先文档、后实现)
日期 2026-08-04
原则 不指定语言;靠库文件名区分中英(及日后其它语言)
相关 stdlib.md · stdlib-modules.md · keywords.md · keywords-i18n.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)
导入 表:lib/表.mq.md 行数 · 取行

示例:

---
import:
  text: lib/text.mq.md
---

# main
*`xs` = > split value=a,b,c sep=,*
---
导入:
  文本: 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 翻译。官方只提供:

lib/json.mq.md    # 中英文档均 `import json:lib/json.mq.md`;函数 parse / stringify / get / keys

不设 lib/数据.mq.md 等平行文件。其余模块仍遵守 §2.1。详见 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. 目录与扩展约定

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 只列 L0;L1 指向本文 + stdlib.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——无语言开关。