Skip to content

[Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000

Description

@eltociear

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:

  1. 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.
  2. 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.
  3. 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。

AGENTS.md 规定仓库根目录只保留 README.md、README.zh-CN.md、AGENTS.md、CHANGELOG.md,新文档放在 docs/,并且默认中英双语,单语文档需在 docs/index 中说明原因。因此在根目录新增 README.ja.md 不符合现行规则。可选方案:

  1. docs/readme.ja.md:完整翻译 README.md,登记到 docs/index.md 和 docs/index.zh-CN.md 并注明是 README 的译本,在 README 的语言链接中加入「日本語」。相对链接按 docs/ 位置调整。
  2. 例外允许根目录的 README.ja.md:与现有两个 README 并列。这会改变根目录规则,需要您批准。
  3. 不加日文 README:如果不想维护第三种语言,完全没问题,我会关闭此 issue。

如果选择 1 或 2,我会提交引用本 issue 的 PR,分支名按 YYYY-MM-DD_short-title。译文会借助 AI 起草。

Activity

  1. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    2 README..md

  2. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    docs but not only readme for ja is good if you can . thanks for your issue

  3. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    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:

    1. 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).
    2. Add a 日本語 entry to the README language-links line — in both README.md and README.zh-CN.md, for parity.
    3. Amend the root-file rule in the same PR — it currently says the root keeps only 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” bullet
      • 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.
    4. Body references GitHub issue [Docs] Japanese README: where should it live? | [文档] 日文 README 应该放在哪里? #6000 (Closes #6000); branch named YYYY-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.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.

  4. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    查重:不重复(已检索 open+closed 的 issue 与 PR,无既有「日文 README」相关条目)。

    @ranxianglei 你的裁定我按这样理解,偏了请纠正:

    • 选 2 —— 根目录放 README.ja.md(用 GitHub 原生 README.<locale>.md 命名);
    • 「docs but not only readme for ja is good if you can」记为可选加分项:日文不止翻 README、能多覆盖一些 docs 更好,量力而为,不作硬性要求。

    落地前置:现行规则明文写「根目录只保留四个入口文件」,共 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」是可选的,看情况来。

  5. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    规则口子 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 了:

    1. 根目录新增 README.ja.md(完整日文翻译);
    2. 在 README.md 与 README.zh-CN.md 第 3 行的语言链接里各加一项 | <a href="./README.ja.md">日本語</a>;
    3. PR body 用 Closes #6000(GitHub 号),分支名 YYYY-MM-DD_short-title。

    两个 PR 文件不重叠,可并行开;只是建议规则 PR(#6001)先合、译文随后。你的翻译 PR 我会重点 review(对照源 README.md 的对应关系、相对链接正确性)。另外你提的「多翻一些 docs」我记为后续增量,量力而为即可。

  6. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    规则口子已落地:**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 合并后顺序更干净,但也可并行——两边文件不重叠):

    1. 仓库根目录新增 README.ja.md(完整日文翻译);
    2. README.md 与 README.zh-CN.md 第 3 行语言链接各加一项 | <a href="./README.ja.md">日本語</a>;
    3. PR body 用 Closes #6000,分支名 YYYY-MM-DD_short-title。

    我会 review 你的翻译 PR(核对与源 README.md 的对应关系、相对链接正确性)。若需要我代笔起草也行,说一声即可。「多翻一些 docs 成日文」是可选加分项,按价值分批来就好。

  7. eltociear commented on Nov 9, 2026

    @eltociear
    ContributorAuthor

    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:

    1. 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)?
    2. 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?
    3. 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.
    4. 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.


    谢谢!README 的 PR 已提交:#6004(根目录 README.ja.md,并在两个 README 中加入「日本語」链接,Closes #6000)。

    关于后续把更多文档翻译成日文,现行文档布局规则还没有覆盖第三种语言,开始前想先确认几点:

    1. 命名与位置:在现有的 docs/<name>.md / docs/<name>.zh-CN.md 旁边放 docs/<name>.ja.md(例如 docs/architecture.ja.md)可以吗?
    2. 索引:每个日文页面是否要登记到 docs/index.md / docs/index.zh-CN.md(例如在该页所在行加一个「日本語」链接),还是等一组翻译完成后再登记?
    3. 顺序与节奏:建议每页一个 PR,先从面向读者、改动较少的页面开始:docs/architecture.md 及 docs/architecture/ 下的模块页,然后是 docs/clients.md。docs/configuration.md 这类体量大或经常重新生成的页面放到最后,如果同步成本太高也可以不翻。
    4. 同步:英文页面更新后,日文页面是否可以暂时滞后、等人更新(在页首注明对应的英文版本)?还是您更希望不要有可能过时的页面?

    如果您更希望日文只保留 README,也完全没问题。译文会借助 AI 起草。

  8. added a commit that references this issue on Nov 9, 2026
  9. ranxianglei commented on Nov 9, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    🔶 需要决策
    (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 下,符合布局规则。
    • 索引:落地即登记。现有规则本就强制每个新增/移动文档在同一 PR 同时进 docs/index.md 和 docs/index.zh-CN.md,所以每页加一个「日本語」链接即可(index 条目注明"日本語訳 of <EN 页>"),不等整组完成。
    • 顺序/节奏:赞成你的方案——每页一 PR,先 docs/architecture.md + docs/architecture/ 模块页(面向读者、少变),再 docs/clients.md;docs/configuration.md 这类大/常重生成页放最后或跳过。

    待 @ranxianglei 拍板(文档布局属 owner 裁定区,我不擅自把规则扩到第三语言):

    • 待决:是否正式开 docs/ 日文轨?同步策略怎么定?
    • 选项:
      • A(推荐)有界滞后 + 页首溯源注:日文页允许暂时落后英文,页首注明"译自 <EN 页> @ <EN 版本/日期>",review 时标漂移。对 AI 起草 + 社区节奏最可持续。
      • B 强同步:英文一改就须同 PR 更新日文,否则撤下该日文页。维护成本高,AI 起草下易反复掉页、拖垮整轨。
      • C 仅 README:docs/ 不开日文轨,日文只保留根 README.ja.md([PR] docs: permit root README.<locale>.md community translations (#6000) #6001 已批并合入的例外已覆盖)。最省事,但放弃此前"多翻些 docs 也好"的方向。
    • 推荐 A:本质是把 .ja.md 并入现有 zh-CN 约定(命名/双索引/同步),再加一条溯源注,不另立规则。
    • 不决定的默认行为:维持现状——docs/ 保持 EN+ZH,日文仅限根 README,不扩规则;等你明确后再动。

    结构化八问

    1. 是什么问题:是否把日文正式纳入 docs/(不止根 README),及同步策略如何定。
    2. 什么原因导致的:现行文档布局规则只覆盖 EN+ZH 双语,第三种语言没有命名/索引/同步约定,贡献者需先确认再开工。
    3. 影响范围与严重程度(按选项):A 低——纯新增若干 docs/*.ja.md,不动现有 EN/ZH 行为;B 中——每次英文改动牵动日文,维护成本上升;C 无——维持现状。均属文档范畴(p3),非可用性缺陷。
    4. 怎么修复的(推荐 A 的思路):沿用 zh-CN 既有约定(.ja.md 命名、同 PR 双索引、one-hub),每页加"译自 <EN 页> @ <rev>"溯源注,允许有界滞后、review 标漂移——并入现有体系而非另立一套。
    5. 是否有回归问题(按选项):A/C 纯新增文件,不涉及既有行为变更;B 若执行不当可能让英文页因等日文而延迟合并(流程风险,非代码回归)。
    6. 是否破坏缓存:不涉及(纯文档)。
    7. 是否改了设计方向:A 小幅扩展文档布局(owner 裁定区),不改代码架构/数据流。
    8. 是否引入了新的配置:不涉及 env/config/knob;只是文档命名与索引约定(Documentation Layout 规则文字)。

    @eltociear 谢谢你的 README PR 和这份细致的约定清单——机械层面(Q1–Q3)已定,随时可按上面推进;只差 @ranxianglei 一句 go/no-go(认同 A 我随即补完规则文字你就开工,或选 B/C)。#6004 的完整内容 review(源对照 + 相对链接)我会单独做。

  10. added a commit that references this issue on Nov 9, 2026
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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions