You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000
I'd like to contribute a Japanese translation of the README and am opening an issue first, as AGENTS.md asks ("file the issue first, then link it").
AGENTS.md also says the repo root keeps only README.md, README.zh-CN.md, AGENTS.md and CHANGELOG.md, that new docs go in docs/, and that bilingual en + zh-CN is the default, with a single-language doc stating why in docs/index. So a root README.ja.md would not fit the current rules. I see these options:
docs/readme.ja.md: a full Japanese translation of README.md, listed in docs/index.md and docs/index.zh-CN.md with a note that it is a translation of the README, and linked from a 日本語 entry in the README's language links. Relative links would be adjusted for the docs/ location.
An exception for a root README.ja.md: next to the existing two READMEs, where GitHub readers usually look for translations. This needs your approval, since it changes the root-file rule.
No Japanese README: if you'd rather not maintain a third language, that's completely fine and I'll close this.
If you pick 1 or 2, I'll send a PR that references this issue, with a branch named YYYY-MM-DD_short-title. The translation would be drafted with AI assistance.
我想为 README 贡献一份日文翻译,按照 AGENTS.md 的要求("file the issue first, then link it")先开 issue。
Thanks @ranxianglei — confirmed: option 2, a root-level README.ja.md (following the README.<lang>.md convention).
@eltociear thanks for the well-scoped issue — you're cleared to open the PR. To make it complete in one pass, please include:
New README.ja.md at the repo root — full JA translation. Bonus of the root location: its internal relative links stay identical to README.md (no docs/ path adjustment).
Add a 日本語 entry to the README language-links line — in both README.md and README.zh-CN.md, for parity.
Amend the root-file rule in the same PR — it currently says the root keeps onlyREADME.md, README.zh-CN.md, AGENTS.md, CHANGELOG.md, so the new file would contradict it unless updated:
docs/index.md (line 3) + its docs/index.zh-CN.md mirror
Suggested bounded wording: the root keeps the four core files plus recognized community-maintained README.<locale>.md translations — admits the JA README without opening the door to arbitrary extra root files.
On the stretch goal (JA docs, not just the README, “if you can”): welcome in principle, but I’d phase it rather than bundle it. docs/ is large and constantly updated (architecture hub + per-module pages, identity/protocol, generated config reference, technical-notes…), so a full JA docs pass is a real ongoing-sync cost. Suggest PR #1 = README.ja.md only, then JA docs as incremental follow-ups (highest-value pages first), only if the maintainer wants to commit to keeping them in sync — flagging the maintenance cost before we widen scope.
I’ll review the PR when it lands (fidelity vs. source, correct links, rule-amendment completeness). Happy to draft it myself if you’d prefer — just say so.
Thanks! The README PR is up: #6004 (root README.ja.md + the 日本語 link in both READMEs, Closes #6000).
On the follow-up of translating more docs into Japanese, a few things to settle before I start, since the docs layout rules don't cover a third language yet:
Naming and location. Would docs/<name>.ja.md next to the existing docs/<name>.md / docs/<name>.zh-CN.md work (for example docs/architecture.ja.md)?
Index. Should each Japanese page be listed in docs/index.md / docs/index.zh-CN.md (for example as a 日本語 link on the page's row), or kept out of the index until a set is complete?
Order and pace. I'd suggest one PR per page, starting with the reader-facing pages that change least often: docs/architecture.md and the module pages under docs/architecture/, then docs/clients.md. Large or frequently regenerated pages such as docs/configuration.md would come last, or be skipped if keeping them in sync is too costly.
Sync. When an English page changes, is it fine for the Japanese page to lag until someone updates it (with a note at the top saying which English revision it follows), or would you rather not have pages that can go stale?
If you'd rather keep Japanese to the README only, that's completely fine too. Translations would be drafted with AI assistance.
Activity
ranxianglei commentedon Nov 9, 2026
2 README..md
ranxianglei commentedon Nov 9, 2026
docs but not only readme for ja is good if you can . thanks for your issue
ranxianglei commentedon Nov 9, 2026
Thanks @ranxianglei — confirmed: option 2, a root-level
README.ja.md(following theREADME.<lang>.mdconvention).@eltociear thanks for the well-scoped issue — you're cleared to open the PR. To make it complete in one pass, please include:
README.ja.mdat the repo root — full JA translation. Bonus of the root location: its internal relative links stay identical toREADME.md(nodocs/path adjustment).日本語entry to the README language-links line — in bothREADME.mdandREADME.zh-CN.md, for parity.README.md,README.zh-CN.md,AGENTS.md,CHANGELOG.md, so the new file would contradict it unless updated:AGENTS.md→ §Documentation Layout, “One hub” bulletdocs/index.md(line 3) + itsdocs/index.zh-CN.mdmirrorSuggested bounded wording: the root keeps the four core files plus recognized community-maintained
README.<locale>.mdtranslations — admits the JA README without opening the door to arbitrary extra root files.Closes #6000); branch namedYYYY-MM-DD_short-title.On the stretch goal (JA docs, not just the README, “if you can”): welcome in principle, but I’d phase it rather than bundle it.
docs/is large and constantly updated (architecture hub + per-module pages, identity/protocol, generated config reference, technical-notes…), so a full JA docs pass is a real ongoing-sync cost. Suggest PR #1 =README.ja.mdonly, then JA docs as incremental follow-ups (highest-value pages first), only if the maintainer wants to commit to keeping them in sync — flagging the maintenance cost before we widen scope.I’ll review the PR when it lands (fidelity vs. source, correct links, rule-amendment completeness). Happy to draft it myself if you’d prefer — just say so.
ranxianglei commentedon Nov 9, 2026
查重:不重复(已检索 open+closed 的 issue 与 PR,无既有「日文 README」相关条目)。
@ranxianglei 你的裁定我按这样理解,偏了请纠正:
README.ja.md(用 GitHub 原生README.<locale>.md命名);落地前置:现行规则明文写「根目录只保留四个入口文件」,共 5 处——
AGENTS.md§3「Documentation Layout」(L156)、docs/index.md(L3)、docs/index.zh-CN.md(L3)、docs/README.md(L3)、docs/README.zh-CN.md(L3)。根目录新增README.ja.md会与之冲突。这是文档性规则、非 CI 硬门禁(CI 的tools/check-architecture-docs.mjs只查架构文档覆盖,不查根目录文件清单),所以不挡 PR;但为避免「写死的规则」和「刚批准的做法」漂离,我会先给这 5 处补一个有界例外:根目录允许受认可的社区 README 译本README.<locale>.md(如README.ja.md,批准于 2026-11-09),四个核心入口文件仍锁定、非译文新文档仍一律进docs/。@eltociear:规则例外我马上开一个小 PR(链接随后贴)。你可以按选项 2推进——在仓库根目录新建
README.ja.md(完整翻译README.md)、在README.md/README.zh-CN.md的语言行加「日本語」入口;PR 引用本 issue、分支名YYYY-MM-DD_short-title。相对链接按根目录位置写(不像放docs/那样改层级)。「多翻 docs」是可选的,看情况来。ranxianglei commentedon Nov 9, 2026
规则口子 PR 已开好:**https://github.com/ranxianglei/billion-context/pull/6001**(label:documentation / p3 / scope/docs)。
这个 PR 只改那 5 处规则文字、不动任何代码或译文:把「仓库根目录只保留四个入口文件」修订为「四个核心入口文件 + 受认可的社区 README 译本
README.<locale>.md」,英文/中文文档四处保持一致。CI 在跑,按 §7.2 以远端为准,绿了我再确认。@eltociear 前置就绪,可以开你的翻译 PR 了:
README.ja.md(完整日文翻译);README.md与README.zh-CN.md第 3 行的语言链接里各加一项| <a href="./README.ja.md">日本語</a>;Closes #6000(GitHub 号),分支名YYYY-MM-DD_short-title。两个 PR 文件不重叠,可并行开;只是建议规则 PR(#6001)先合、译文随后。你的翻译 PR 我会重点 review(对照源
README.md的对应关系、相对链接正确性)。另外你提的「多翻一些 docs」我记为后续增量,量力而为即可。ranxianglei commentedon Nov 9, 2026
规则口子已落地:**https://github.com/ranxianglei/billion-context/pull/6001**(已开、已打标签
documentation/p3/scope/docs)。这个 PR 只做一件事——给「根目录只保留四个入口文件」的 Documentation Layout 规则开口子,5 处一致修订(
AGENTS.md§Documentation Layout、docs/index{,.zh-CN}.md、docs/README{,.zh-CN}.md):根目录额外允许受认可的社区 README 译本README.<locale>.md(如README.ja.md,2026-11-09 批准);四个核心入口文件仍锁定、非译文新文档仍一律进docs/。纯文档改动,不碰代码 / wire / config。CI 正在跑(刚查过镜像缓存:当前无失败,测试分片进行中)。PR body 用
Refs #6000而非Closes——因为本 issue 真正完成要等你的译文落地,我这个只是前置规则,不该替它关单。@eltociear 现在可以开你的翻译 PR 了(等 #6001 合并后顺序更干净,但也可并行——两边文件不重叠):
README.ja.md(完整日文翻译);README.md与README.zh-CN.md第 3 行语言链接各加一项| <a href="./README.ja.md">日本語</a>;Closes #6000,分支名YYYY-MM-DD_short-title。我会 review 你的翻译 PR(核对与源
README.md的对应关系、相对链接正确性)。若需要我代笔起草也行,说一声即可。「多翻一些 docs 成日文」是可选加分项,按价值分批来就好。eltociear commentedon Nov 9, 2026
Thanks! The README PR is up: #6004 (root
README.ja.md+ the日本語link in both READMEs,Closes #6000).On the follow-up of translating more docs into Japanese, a few things to settle before I start, since the docs layout rules don't cover a third language yet:
docs/<name>.ja.mdnext to the existingdocs/<name>.md/docs/<name>.zh-CN.mdwork (for exampledocs/architecture.ja.md)?docs/index.md/docs/index.zh-CN.md(for example as a日本語link on the page's row), or kept out of the index until a set is complete?docs/architecture.mdand the module pages underdocs/architecture/, thendocs/clients.md. Large or frequently regenerated pages such asdocs/configuration.mdwould come last, or be skipped if keeping them in sync is too costly.If you'd rather keep Japanese to the README only, that's completely fine too. Translations would be drafted with AI assistance.
谢谢!README 的 PR 已提交:#6004(根目录
README.ja.md,并在两个 README 中加入「日本語」链接,Closes #6000)。关于后续把更多文档翻译成日文,现行文档布局规则还没有覆盖第三种语言,开始前想先确认几点:
docs/<name>.md/docs/<name>.zh-CN.md旁边放docs/<name>.ja.md(例如docs/architecture.ja.md)可以吗?docs/index.md/docs/index.zh-CN.md(例如在该页所在行加一个「日本語」链接),还是等一组翻译完成后再登记?docs/architecture.md及docs/architecture/下的模块页,然后是docs/clients.md。docs/configuration.md这类体量大或经常重新生成的页面放到最后,如果同步成本太高也可以不翻。如果您更希望日文只保留 README,也完全没问题。译文会借助 AI 起草。
Merge pull request #6001 from ranxianglei/2026-11-09_root-readme-tran…
docs: allow root README.<locale>.md community translations (ranxiangl…
ranxianglei commentedon Nov 9, 2026
🔶 需要决策
(ai: vllm-qwen/qwen3.8-27b)
背景一句话:把日文正式纳入
docs/(不止根 README)需你定两件事——是否开第三语言轨 + 同步策略;其余三点沿用现有文档规则即可。顺带两件已核实的事:root README 的例外(#6001)刚合入 master;贡献者的日文 README 译文 PR #6004 我已核验干净(仅 3 个文件:新增README.ja.md+731、两个 README 各加一行「日本語」链接,无夹带改动)。@eltociear,这三点按现有规则即可办,无需新决策:
docs/<name>.ja.md与.md/.zh-CN.md并列 ✓ —— 和.zh-CN.md同一套后缀模式,仍在docs/one-hub 下,符合布局规则。docs/index.md和docs/index.zh-CN.md,所以每页加一个「日本語」链接即可(index 条目注明"日本語訳 of <EN 页>"),不等整组完成。docs/architecture.md+docs/architecture/模块页(面向读者、少变),再docs/clients.md;docs/configuration.md这类大/常重生成页放最后或跳过。待 @ranxianglei 拍板(文档布局属 owner 裁定区,我不擅自把规则扩到第三语言):
docs/日文轨?同步策略怎么定?docs/不开日文轨,日文只保留根README.ja.md([PR] docs: permit root README.<locale>.md community translations (#6000) #6001 已批并合入的例外已覆盖)。最省事,但放弃此前"多翻些 docs 也好"的方向。.ja.md并入现有 zh-CN 约定(命名/双索引/同步),再加一条溯源注,不另立规则。docs/保持 EN+ZH,日文仅限根 README,不扩规则;等你明确后再动。结构化八问
docs/(不止根 README),及同步策略如何定。docs/*.ja.md,不动现有 EN/ZH 行为;B 中——每次英文改动牵动日文,维护成本上升;C 无——维持现状。均属文档范畴(p3),非可用性缺陷。.ja.md命名、同 PR 双索引、one-hub),每页加"译自 <EN 页> @ <rev>"溯源注,允许有界滞后、review 标漂移——并入现有体系而非另立一套。@eltociear 谢谢你的 README PR 和这份细致的约定清单——机械层面(Q1–Q3)已定,随时可按上面推进;只差 @ranxianglei 一句 go/no-go(认同 A 我随即补完规则文字你就开工,或选 B/C)。#6004 的完整内容 review(源对照 + 相对链接)我会单独做。
docs: add Japanese README (#6000)
Merge pull request #6004 from eltociear/2026-11-09_add-japanese-readme
docs: sync stagger-default wording in post-base files (README.ja, lif…
docs: sync stagger-default wording in post-base files (README.ja, lif…
docs: sync stagger-default wording in post-base files (README.ja, lif…
docs: sync stagger-default wording in post-base files (README.ja, lif…