Skip to content

All repository documentation is available in Japanese. | 仓库所有文档都提供日文版本 #6072

Closed

Description

@ranxianglei

仓库所有文档都提供日文版本

Activity

  1. changed the title [-]仓库所有文档都提供日文版本[/-] [+]All repository documentation is available in Japanese. | 仓库所有文档都提供日文版本[/+] on Nov 10, 2026
  2. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    🔍 查重结论:不重复。 与已合并的 #6000 / #6001 / #6004 相关但不同 —— 那三个已完成日文 README(README.ja.md,731 行)并确立了根目录 README.<locale>.md 的例外规则,且 PR #6004 明确把「其余文档」留给后续 follow-up。本 issue 正是那个后续:把日文覆盖从 README 扩到全仓文档。机制不同(locale 例外规则 vs 全量文档翻译),单独立项合理。

    现状盘点(已在最新 master 上核对,非旧快照):

    • ✅ README.ja.md 已有([PR] docs: add Japanese README (#6000) #6004)。
    • T1 · 有中文孪生的手写文档(~20 个文件,~39K 词):docs/ 下 architecture 枢纽 + 9 个模块页、clients、technical-notes、message-identity、session-identity、session-identity-resolution、identity-channels、msgid-infrastructure、opencode-responses-websocket、index、README(dir),以及根目录几个 redirect stub(CLIENTS / CONFIGURATION / MESSAGE-IDENTITY / SESSION-IDENTITY / TECHNICAL-NOTES)。
    • T2 · 生成的配置文档:docs/configuration.md(58K 词)由 website/config-reference/*.yaml + tools/gen-config-docs.mjs 生成,还牵动 website UI 的 en/zh i18n(main.js / index.html)与 ci.yml:553 的确定性检查。
    • T3 · 目前无中文版本的文件:CHANGELOG.md(31K)、AGENTS.md(6.6K)、reference/* 构造流程(release / testing / architecture / design-decisions / env-vars 等 ~16K)、少数暂无 zh 的 docs(lifecycle / plugin-protocol / auto-merge-guardrails / unified-loop-spec ~9K)。

    方案(命名沿用 README.ja.md 已定的 .ja.md 短 locale;既有 .zh-CN.md 与 .ja.md 不一致属历史遗留,本次不强行统一):

    • Phase 1(我现在就做):给 T1 每个文档补 .ja.md,登记进 docs/index.md + docs/index.zh-CN.md,并在页面语言链接加「日本語」。按章节分批提交到同一个针对 All repository documentation is available in Japanese. | 仓库所有文档都提供日文版本 #6072 的长期 PR,CI 把关。
    • Phase 2(随后):T2 生成的配置文档 —— 改生成器 + 给 yaml 每条补 desc_ja / site_ja + website UI i18n + ci 确定性检查。工作量最大的一块。
    • Phase 1 + 2 合起来就覆盖了所有「用户/评审真正读的文档」,符合「所有文档」的本意。

    🔶 需要决策(仅一个边界,不阻塞开工)

    • 背景:T3 的那批文件(CHANGELOG / AGENTS.md / reference/*)今天就没有中文版,仓库惯例把它们当英文专用。是否也要日文,想听你一句。
    • 待决:CHANGELOG.md、AGENTS.md、reference/* 要不要一并出日文版?
    • 选项 + 代价:① 保持英文(默认)—— 与现有中文覆盖边界一致,零额外维护;② 也出日文 —— 字面彻底「所有文档」,+~50K 词,其中 CHANGELOG 本地化价值低、长期维护负担高。
    • 推荐:保持英文(CHANGELOG 变更日志按惯例不本地化、AGENTS.md 是内部 agent 契约、reference 是 agent 懒加载流程 —— 三者当前都以英文为准,强行出日文收益低)。
    • 不决定的默认行为:我按「保持英文」推进,专注把 T1 + T2 做扎实;你若想要某一块的日文,点一下我就扩展。

    标签:documentation / scope/docs / p3(纯文档本地化的功能补齐,非缺陷、不影响可用性 → p3)。注:本环境镜像标签接口返回「endpoint not implemented」、tools/add-label.sh 也不在 tools/ 下,无法程序化打标,故在此写明意图供你/平台补打。

    我现在开始 Phase 1 第一批(「身份与协议」整章:docs/README、index、message-identity、session-identity、session-identity-resolution、identity-channels、msgid-infrastructure、opencode-responses-websocket),完成后回帖 PR 链接。

  3. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    进度更新 · 第 1 批已交付

    PR 已开:#6076 — #6076 (标签 documentation + p3,按本 PR diff 独立判定)。分支 2026-11-10_japanese-docs,后续批次继续往同一分支追加提交(一个 thread 一个 PR)。

    本批范围(身份与协议 section,4 篇)

    • docs/session-identity-resolution.ja.md
    • docs/identity-channels.ja.md
    • docs/msgid-infrastructure.ja.md
    • docs/opencode-responses-websocket.ja.md
    • docs/index.md / docs/index.zh-CN.md:新增译文行各补一条 [日本語] 链接。

    顺手小修:README.ja.md(#6004 已加)此前从未在 index 里被引用,这次在 README 行补上 [日本語](../README.ja.md),与其它语言保持一致、可被发现。

    约定(沿用 #6004 README.ja.md 先例)

    • 命名 .ja.md(短 BCP47),对齐最新 owner 决定;
    • 日文 = 英文源的忠实完整镜像(无损:围栏代码块逐字节保留、表格 / 行内代码 / issue 引用照原样)。已有的 .zh-CN.md 若属精简/重排过,日文不继承那些缺口。

    CI 安全:纯文档改动,无 config / wire / 代码变更、无新 env var;文件不在 docs/architecture/ 下,architecture-docs 守卫不受影响;未动 gen-config-docs.mjs 产物,docs-sync 确定性检查不受影响。

    剩余路线(同分支后续批次)

    1. 身份与协议收尾:message-identity、session-identity
    2. Start here:clients、technical-notes;architecture hub + 各模块页(需同步改 tools/check-architecture-docs.mjs 接受 .ja.md slug)
    3. 工程运维:lifecycle、auto-merge-guardrails、unified-loop-spec、plugin-protocol、reference/*
    4. 生成类:configuration.md(扩展 tools/gen-config-docs.mjs + ci.yml 那行确定性检查)

    🔶 需要决策

    • 背景:上一轮列出的 T3「无中文先例」文件——CHANGELOG.md、AGENTS.md、reference/*。
    • 待决:这些是否也要出日文版?
    • 选项与代价:
      • A(推荐)保持英文不译:AGENTS.md/CHANGELOG.md 是面向贡献者/发版的活文档,日文化后每次更新都要跟翻、易漂移;reference/* 是惰性加载的施工参考,读者本就是开发者。
      • B 全译:覆盖面更完整,但约再多 ~16K 词,且 CHANGELOG/AGENTS 长期维护负担明显上升。
    • 推荐 + 默认行为:选 A(只译 T1 手写正文 + T2 生成的 configuration.md)。若不回复,我按 A 推进、不停工。

    我继续往下译并追加到 #6076。

  4. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

    身份与协议板块收尾完成 —— 该章 6 篇日文本现已齐全。

    PR #6076(本 issue 唯一长期 PR)又追加了一个提交 f1c13181:
    #6076

    本次新增 2 篇(补齐该章):

    • docs/message-identity.ja.md(含 wire-bytes 代码块,逐字节与英文源一致)
    • docs/session-identity.ja.md
    • docs/index.md / docs/index.zh-CN.md:这两行各补 [日本語] 链接。

    至此「身份与协议」整章 6 篇全部译出并登记:opencode-responses-websocket / session-identity-resolution / identity-channels / msgid-infrastructure / message-identity / session-identity。质量对账通过——EN↔JA 标题数、代码块数、表格列、issue 引用数逐项一致,围栏代码逐字节相等,扫过中文残留词与列表缩进均干净。

    一个插曲(已妥善处理,无损失):本轮动手前发现分支上其实已有前几轮推送的提交 + 4 个质量修复(恢复漏掉的 responsesCodec 名、列表项空格、图表缩进对齐、index 语言标签交叉修正)。我没有强推覆盖,而是把本地重置回远端最新(完整保留那 4 个修复),再把这 2 篇新译文以新提交 fast-forward 叠上去——历史线性、无 force-push、无丢失。

    CI:上一 head(fa31da6e)的快速门禁已全绿(docs-sync / config-surface-guard / lifecycle-ledger-guard / unused-exports 等);新 head 的检查刚触发、镜像缓存还没刷到它。纯 markdown 变更,无 config/wire/env 改动,功能风险为零。

    🔶 决策仍待你一句(同 floor 3/4,不阻塞进行中工作):根级运维文件 CHANGELOG.md / AGENTS.md / reference/* 默认保持英文不译(无中文先例、维护负担高)。要其中某些也出日文,点一下即可。

    我继续往下做「工程与运维」批(先 lifecycle / auto-merge-guardrails / unified-loop-spec / plugin-protocol,再啃 clients / technical-notes 两大篇),陆续追加到 #6076。

  5. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    进度更新 · 身份与协议部分已全部完成

    PR #6076 当前 head 9ceb10f(已提交并推送):

    已完成

    • 身份与协议 6 篇全齐:message-identity / session-identity / session-identity-resolution / identity-channels / msgid-infrastructure / opencode-responses-websocket
    • 目录落地页 docs/README.ja.md(忠实镜像英文版),并在两个 index 的对应行补了日文链接
    • index.md / index.zh-CN.md 里所有已完成条目都挂了 [日本語] 链接

    CI(新 head 实测):快速门全绿(docs-sync / docs-coverage / architecture-docs / config-surface-guard / lifecycle-ledger-guard 等),0 失败,仅完整 test 分片还在跑。纯文档新增不影响代码测试。分支目前落后 master 几步,合并前我会 rebase。

    范围修正(重要)
    我上一条说"接下来做工程与运维"——细看后要修正:该分区里只有 technical-notes 有中文版;lifecycle / auto-merge-guardrails / unified-loop-spec 都没有中文版(刻意单语:auto-merge-guardrails 本就是中文专属的证据附录)。身份分区里的 plugin-protocol 同样无中文版(标注"实验性,无中文版")。所以这 4 篇不算核心日文工作,归入下方"默认排除"档。

    剩余在范围内(已有 en+zh、尚缺 ja)

    1. clients.md(约 1.15 万词,大)
    2. technical-notes.md(约 1.1 万词,大)
    3. architecture 总览页 + 9 个模块页(需扩展 tools/check-architecture-docs.mjs 接受 .ja.md slug;图的问题见下)
    4. configuration.md(生成物,见下)
      另:根目录 5 个重定向占位(CLIENTS / CONFIGURATION / MESSAGE-IDENTITY / SESSION-IDENTITY / TECHNICAL-NOTES)随各自目标一起补。

    两个实现子问题(附建议,供拍板一并看)

    • 架构图:架构页每页带语言专属 SVG(en / zh-CN 各一套)。严格镜像的话日文要 .ja.svg。建议先复用现有图、页面加一行"图参照英文版",不重画 10 张矢量图(图内多为英文标识符,重画成本高价值低);要高保真再单独排期出 ja 版。
    • configuration.md 由 tools/gen-config-docs.mjs 从 website/config-reference/*.yaml 生成。正确做法是扩生成器 + 提供 ja 源串;否则只能手写一份快照,后续配置变更会漂移且不受守卫。建议这篇走生成器扩展或暂缓,单列处理。

    🔶 需要决策

    • 背景:issue 标题是"所有文档提供日文",但本仓库惯例是 EN+ZH 双语,且有若干文件刻意保持单语。
    • 待决:日文覆盖范围 = 精确对齐中文版(推荐),还是全覆盖(把没有中文版的也翻出来)?
    • 选项代价:
      • A 对齐中文版(推荐):只给"已有 en+zh"的文件补 ja;跳过 CHANGELOG.md / AGENTS.md / reference/* 及那 4 篇无中文文件。工作量可控、三语对齐、尊重既有单语设计。
      • B 全覆盖:额外翻译上述文件(部分无英文源,需从中文译,会改变其单语状态)。工作量明显更大。
    • 推荐 A。不决定的默认行为:按 A 继续——完成 clients / technical-notes / architecture / configuration 四类后收工。

    下一条我继续啃 clients.md。

  6. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    本轮收工确认(上一条是详细展开,这里给结论):

    • 身份与协议 6 篇日文全部完成 + 目录落地页 docs/README.ja.md,均已提交并推送到 PR [PR] docs: add Japanese versions of repository documentation (#6072) #6076(head 9ceb10f,工作树干净)。
    • index.md / index.zh-CN.md 对应行都补了 [日本語] 链接。
    • CI 新 head 实测:快速门全绿(docs-sync / docs-coverage / architecture-docs / config-surface-guard 等)、0 失败,仅完整 test 分片还在跑(纯文档新增不影响代码测试)。
    • 待你拍板:日文覆盖范围 = 精确对齐中文版(推荐) 还是 全覆盖?不回答我默认按"对齐中文版"继续。
    • 下一条继续 clients.md(约 1115 行、代码标识符密集,单独一轮做以保证质量),随后 technical-notes → architecture → configuration。
  7. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    主要搞readme和docs即可 AGENTS.md是给llm看的 不需要日文
    建议一个pr搞定 不要拆分

  8. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    收到,范围锁定:

    据此,剩余待做(全部进 #6076):

    • clients.md(约 1.1 万词,大)← 现在就开始
    • technical-notes.md(约 1.1 万词)
    • architecture 总览页 + 9 个模块页(需扩展 tools/check-architecture-docs.mjs 收 .ja.md slug;图沿用英文版并加一行说明,不重画矢量图)
    • configuration.md(生成物,走生成器扩展或单列处理)

    边界确认(若与你意图不符请纠正):CHANGELOG.md 与 reference/* 不在"readme + docs"范围内,默认不做;docs/ 里那 4 篇刻意单语、无中文版的(lifecycle / auto-merge-guardrails / plugin-protocol / unified-loop-spec)也默认保持英文。需要哪篇再单独说。

    现在开始啃 clients.md。

  9. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    进度汇报(刚才进程在生成大文件时超时被重启,已恢复,继续推进):

    已完成并推送(PR #6076,head 9ceb10f,CI 快速门全绿、0 失败):

    • 身份与协议 6 篇日文(identity-channels / message-identity / msgid-infrastructure / opencode-responses-websocket / session-identity-resolution / session-identity)
    • 目录落地页 docs/README.ja.md
    • 两份 index 对应行都补了 [日本語] 链接

    当前在做:clients.md —— 全仓最大的一篇(约 1.1 万词 / 1115 行,670 个内联代码段、5 张表、3 个代码块、80 处 issue 引用)。刚才一次性整篇生成导致超时,改为分段写入避免再卡。

    你定的范围我照办:只做 README + docs/,AGENTS.md 排除,一个 PR 不拆分。剩余顺序:clients.md(现在)→ technical-notes.md → architecture 总览+9 模块页(需扩展 check-architecture-docs.mjs 收 .ja.md)→ configuration.md(生成物)。

    继续,稍后交付 clients.ja.md。

  10. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    进度汇报(刚被强制重启过一次,原因是单个超大块生成超时——已改用小块追加,不会再卡):

    已交付(PR #6076,head 9ceb10f,CI 绿):

    • 身份与协议 6 篇日文 + docs/ 目录落地页,均已提交推送。

    正在做:clients.md(全仓最大的一篇,约 1100 行 / 1.1 万词)。当前磁盘状态已核实:

    • 6 个章节里 前 5 节已完成并写盘(dsh、Kimi、Hermes、ZCode、Codex、Gemini 家族、Pi、Kiro、未列表客户端、http.proxy、未识别端点),未提交。
    • 只剩最后一节 OpenCode(约 210 行,含一个纯代理 JSON 配置块)没写完——就是它体量太大导致刚才超时。

    下一步:把 OpenCode 一节拆成 3 个小块追加 → 全文做中英一致性校验(标题数/代码块/表格列/issue 引用逐项对账)→ 修掉几处已知笔误 → 在两份 index 注册 [日本語] 链接 → 提交推送(自动更新 PR #6076)。

    范围按你定的执行:只做 README + docs/,AGENTS.md 不做,全部收进同一个 PR #6076 不拆分。继续推进中。

  11. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    clients.md 已完成并推送(PR #6076,head 438fbe8)——这是全仓最大的一篇(约 1100 行 / 1.1 万词),覆盖 dsh、Kimi、Hermes、ZCode、Codex、Gemini 家族、Pi、Kiro、未列表客户端、http.proxy、OpenCode 全部客户端小节。

    质量核对(对 EN 源逐项对账,全通过):

    • 标题数 24=24、3 个代码块逐字节一致(含列表内嵌的缩进块)、表格列结构与行数一致、issue 引用 118=118;
    • 全文扫过中文残留词与错字并已修正(漂移→ドリフト、レッドダー→ラダー 等),无畸形行内代码。

    过程说明: 推送时发现远端在我这轮之外又落了 2 个质量修订单(README.ja.md / message-identity.ja.md),与本批零文件重叠 → 用 rebase 把本批叠到远端之上(线性历史、双方都保留、未 force-push)。

    CI: 新 head 30 项检查全绿(0 失败);behind 只是 master 前进了,收尾批次前我会再 rebase。

    范围已按你的拍板写进 PR 描述:只做 README + docs/,AGENTS.md 不做;CHANGELOG / reference 不在 "readme+docs" 内;docs/ 里那 4 篇刻意单语、无中文版的默认保持英文。

    下一步:technical-notes.md(约 1.1 万词,同样大),随后 architecture(需扩展 docs 守卫认 .ja.md)→ configuration(生成物,走生成器扩展)。继续推进中。

  12. ranxianglei commented on Nov 10, 2026

    @ranxianglei
    OwnerAuthor

    你是不是直接调用 api 翻译更快?你自己核对即可?

  13. 13 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions