Skip to content

docs: add Japanese README - #8839

Merged
loopx-agent merged 2 commits into
loopx-project:mainfrom
eltociear:add-ja-doc
Nov 16, 2026
Merged

loopx-agent merged 2 commits into
loopx-project:mainfrom
eltociear:add-ja-doc

Conversation

@eltociear

@eltociear eltociear commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

  • Outcome basis / optional anchor: I created Japanese translated README. Documentation request (new reader-facing translation); no issue, roadmap card or RFC anchor.

  • Goal/source and gap: The root README exists in English and Simplified Chinese only. Japanese-speaking users have no README in their language.

  • Observable before → after, with the validation row that proves it: before, the language links in README.md and README.zh-CN.md list English and 简体中文 only; after, both also link [日本語](README.ja.md), and README.ja.md is a 1:1 translation of README.md (see the manual and unit rows).

  • Issue/task and intended base: none; base main.

Author Declaration

  • Written by: model_agent (Claude, by Anthropic), submitted by @eltociear

Implemented against

  • Specification and revision: no written specification; the request in this PR is the basis
  • Criteria:
Criterion (spec clause) Disposition Symbol / path Test or command
Japanese README with the same structure as the English README implemented README.ja.md manual structure comparison (headings, code blocks, table rows, list items, <details>, images, <a id> anchors)
Language links point to the Japanese README implemented README.md, README.zh-CN.md (nav line) manual check of the nav line
README checks that enumerate root README languages cover the new file implemented tests/test_readme_presentation.py, examples/readme-star-history-smoke.py uv run --extra test python -m pytest -q tests/test_readme_presentation.py; uv run --extra test python examples/readme-star-history-smoke.py
Japanese README matches current main, including the Goal stop/resume paragraph from #8840 (review [P2]) implemented README.ja.md (after the five-question table) manual comparison with README.md at 8caf2da
A Japanese-only README edit runs the Frontstage workflow and is classified as docs (review [P2]) implemented .github/workflows/frontstage-pages.yml (pull_request and push paths), scripts/ci/impact_plan.py (ROOT_DOCS), scripts/ci/test_impact_plan.py cd scripts/ci && uv run --project ../.. --extra test python -m pytest -q test_impact_plan.py
  • Self-check before submission: ran the checks in the Validation table. Code blocks, inline code, URLs, badges, image paths and explicit <a id> anchors are unchanged from README.md; in-page links to translated headings point to the Japanese heading slugs, and all 15 resolve. Images use the English assets, as no Japanese assets exist. Following review, README.ja.md was added to ROOT_DOCS and the Frontstage path filters. Left out on purpose: other README-specific smokes, and the HTML maintainer comment in the News section, which stays in English.

Scope And Continuation

  • Completed scope and remaining work: complete within this scope.
  • Slice boundary / successor: N/A; the translation is complete and future README updates need the same sync as the Chinese README.

Validation

Public-safe summaries only, including in HTML comments. Do not paste raw logs,
private data or prompts, private screenshots, credentials, internal URLs, connection
strings, or local paths. Use repository-relative commands without sensitive
arguments, aggregate results, and already-public CI links. If evidence is
private, report its category and limitations only; do not upload it to prove a claim.

  • Tested revision: 6b9b585 (rebased on main 8caf2da; the earlier 82112cc rows are superseded by the rows below)
  • Run state: finished
  • Input classes: none
Check kind Result Public-safe evidence / limitation
unit passed uv run --extra test python -m pytest -q tests/test_readme_presentation.py: Trendshift badge check now also runs on README.ja.md; 3 passed.
static passed uv run --extra test python examples/readme-star-history-smoke.py: star-history section order and image checks, now including README.ja.md; ok.
static passed uv run --extra test loopx check --scan-path README.md --scan-path README.ja.md --scan-path README.zh-CN.md: public boundary scan clean, 3 files.
static passed examples/docs-governance-smoke.py and examples/repository-hygiene-smoke.py: ok.
static failed examples/public_entry/readme-demo-surface-smoke.py fails with AssertionError: long-running agent teams on README.md. It fails identically on unmodified main (f7e3f42); this PR does not touch that string or that smoke.
static passed git diff --check.
unit passed cd scripts/ci && uv run --project ../.. --extra test python -m pytest -q test_impact_plan.py: 6 passed, 29 subtests. The new test_root_readme_locales_are_documents covers README.md, README.zh-CN.md and README.ja.md (A/M/D each, plus all three together). With ROOT_DOCS reverted, it fails on README.ja.md (4 subtests).
static passed .github/workflows/frontstage-pages.yml parses as YAML; README.ja.md added next to README.zh-CN.md in both the pull_request and push path lists.
manual passed Re-ran the README.md / README.ja.md comparison on the rebased tree: headings, fences, table rows, list items, <details>, images, <a id> anchors, code blocks and inline code identical; 15 in-page anchors resolve; CommonMark render leaves no unparsed **.
manual passed Compared README.md and README.ja.md: heading levels, code fences, table rows, list items, <details>/<summary>, <img> and <a id> lists identical; fenced code blocks and inline code identical; links identical except the language link; 15 in-page anchors resolve.
unit not_run Full local CI equivalent (pytest -q, ruff, mypy, canary premerge) not run: the change is Markdown plus two README language lists; runtime is not applicable.
  • Coverage and gaps: the changed paths are three README files and two README checks, and those checks ran. README.ja.md is now in ROOT_DOCS and in the Frontstage path filters, so a later Japanese-only edit is classified as docs and runs the README Star History smoke. This PR itself touches scripts/ci/impact_plan.py (a policy path), so it still runs full qualification.

See validation disclosure guidance.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • First viewport and preview: N/A, no UI impact
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A
  • Craft review: N/A

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Refactoring (no functional changes)
  • Documentation update
  • Test update

LoopX Area

  • Control plane (goals, todos, quota, scheduler, registry, runtime)
  • Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
  • Capability or extension (providers, adapters, skills)
  • Public docs or presentation surface (README, protocols, dashboard)
  • Build, packaging, installer, or CI
  • Host or runtime integration

Technical Direction

  • Direction / acceptance reference, when applicable: N/A

Shared-authority RFC fixture impact

N/A

  • Production-scale fixture schema:
  • Semantic dimensions changed, or reviewed no-impact rationale:
  • Provider conformance arms run:
  • Read-only legacy/file/PostgreSQL three-arm rehearsal (required for promotion, runtime-routing, or compatibility-projection changes):

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Existing English/Chinese RFC pairs (including ledger entries) both have a diff, and the local premerge check python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD passes, or no paired RFC changed.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max

评审提交 82112cc037af32371d06a4dfa278e975af365cec,共同基点 f7e3f427197bab6c66ab535e26613a7f9c2fdbe0,当前主干 f38fae05bb9a1c2cc54a2641359224cc253d32ac。

动机 / Motivation

从仓库首页了解 LoopX 并跟着 README 开始使用的日语读者,需要能用同一语言找到启动、停止和恢复步骤。 从英文或中文 README 切换到日文,点进快速开始,再查怎么由 owner 暂停已开始的 Goal 并恢复资格。 GitHub 的语言切换与快速开始在候选头有效,15 个页内链接均找到目标。把候选合入当前主干模拟时,日文版漏掉了英文和中文已提供的 Goal 停止、恢复和执行条件。 交付范围是仓库 README 及其现有检查。命令的运行行为由原产品入口提供,本轮验证了主干 CLI 参数帮助。

改动思路 / Approach

复用英文信息结构、当前 GitHub Markdown 导航、现有英文图像和共享的首屏与 Star History 验证。 读者能在仓库首屏直接切换语言,在同一版本打开日文快速开始。把完整翻译放在根目录后,要同步主干当前的关键操作说明,也要让已有文件校验随日文更新触发。 主干操作说明 GitHub 日文入口

具体改动 / Changes

5 个文件,新增 976 行、删除 3 行。日文 README 占 972 行,英中两个入口各增加一个语言链接。其余两处扩展已有首屏 badge 测试和 Star History smoke 的输入列表。 逐段核对了安装与权限、可选功能的启用说明、实验比较、许可证和公开链接。相对文件链接在组合树中都找到目标。相同的命令块、披露区段、表格结构与显式锚点都得到保留。 首屏测试 Star History 检查

  • readme-locale-navigation。两种已有语言都可以切换到精确提交的日文 README。浏览器打开精确提交的 GitHub Markdown,实点英文和中文的日本語入口及日文快速开始。 语言导航
  • readme-goal-lifecycle。日文发布还缺主干停止与恢复入口的原有操作条件。 已合入的说明
  • readme-localized-validation。需要验证日文单文件变更能够进入它新增用例所处的工作流。 工作流触发

对主干的风险 / Risks

[P2] 在日文版补齐主干的 Goal 停止和恢复步骤。 当前主干 #8840 在两种 README 都加入了 Goal stop/resume 预览、owner 执行和预期状态指纹。合并模拟得到的日文页仍从五问表直接进入架构折叠,五处关键信息全缺。只读日文说明的操作者能找到开始入口,却必须换语言才能发现受治理的停止和恢复。 更新到主干 #8840 的 README 这一段。保留 stop/resume 预览、owner 执行、已有状态指纹和 loopx-core 入口。 差异位置

[P2] 把日文 README 接入已有的 Star History 检查触发。 这个提交扩展了 Star History smoke 的语言列表,但 Frontstage Pages 的 pull_request 和 main push 路径都只列出原有两种根 README。用单文件改动比对实际 workflow 路径与 CI classifier,日文单独更新会走 full backend/Python 计划,同时跳过专门执行 README Star History smoke 的 Frontstage 工作流。 把 README.ja.md 接入该工作流现有的 pull_request 与 push 路径,再用三个 README-only 输入核对文档分类。 差异位置

正向证明包括 43 个标题、9 个完全相同的 fenced code block 和 117 条可定位的相对文件链接。三项 hero 测试、Star History 与文档治理 smoke 均通过。 按精确共同基点执行 quick premerge,五项直接和四项选定检查通过。本地合并树生成成功。 GitHub CI 按本轮策略未查询。

语义与 CI 对齐

当前候选会因改动已列出的英中 README 和 smoke 文件而触发 Frontstage。后续只改日文文件的情形单独做了对照。现有分类器会启动原本为其他变更保留的后端检查,前台文档检查却没有对应触发。 CI 文件分类 执行 smoke 的步骤

我的整体评价 / Verdict

REQUEST_CHANGES。 日文入口和快速开始已经可以使用。请让同一入口能查到现行的 Goal 停止、恢复与 owner 执行条件,并给日文单文件更新接上正在扩展的前台文档检查。合并树和三种单文件路由都可以直接复验。首屏导航和阅读路线在 GitHub 渲染入口检查。 验证了桌面浏览器的可达性与 DOM。窄屏和完整页面的像素布局未检查。

English verdict: REQUEST_CHANGES at 82112cc. The Japanese navigation works. Sync the current Goal stop/resume instructions and route Japanese-only README edits through the existing Frontstage smoke.

Comment thread README.ja.md
| 次に何が起こるか? | 順序付けられたユーザーとエージェントの todo、オーナーシップ、claim、リース。 |
| 人間の判断が必要なものは何か? | 曖昧な「オーナー待ち」ではなく、具体的なユーザーゲート。 |
| どのエビデンスが変わったか? | コンパクトな実行履歴、検証、ブロッカー、受け入れられた writeback。 |
| ループを続けてよいか? | クォータ、ケイパビリティ、安全なフォールバック、スケジューラーのヒント、停止条件。 |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 在日文版补齐主干的 Goal 停止和恢复步骤。 当前主干 #8840 在两种 README 都加入了 Goal stop/resume 预览、owner 执行和预期状态指纹。合并模拟得到的日文页仍从五问表直接进入架构折叠,五处关键信息全缺。只读日文说明的操作者能找到开始入口,却必须换语言才能发现受治理的停止和恢复。 更新到主干 #8840 的 README 这一段。保留 stop/resume 预览、owner 执行、已有状态指纹和 loopx-core 入口。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6b9b585. I rebased the branch onto main (8caf2da) and translated the Goal lifecycle paragraph from #8840 into README.ja.md, right after the five-question table, in the same place as README.md. It keeps the loopx goal-lifecycle --goal-id <id> --operation stop preview, --operation resume, --actor-kind owner --execute, the fresh --expected-state-fingerprint from the Goal actions view, and the loopx-core link unchanged. I re-ran the structure comparison against README.md on the rebased tree: headings, code blocks, inline code and anchors are identical.

readme_sections = {
ROOT / "README.md": ("## Current Status", "## Star History", "## License"),
ROOT / "README.zh-CN.md": ("## 当前状态", "## Star 趋势", "## License"),
ROOT / "README.ja.md": ("## 現在のステータス", "## Star の推移", "## ライセンス"),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 把日文 README 接入已有的 Star History 检查触发。 这个提交扩展了 Star History smoke 的语言列表,但 Frontstage Pages 的 pull_request 和 main push 路径都只列出原有两种根 README。用单文件改动比对实际 workflow 路径与 CI classifier,日文单独更新会走 full backend/Python 计划,同时跳过专门执行 README Star History smoke 的 Frontstage 工作流。 把 README.ja.md 接入该工作流现有的 pull_request 与 push 路径,再用三个 README-only 输入核对文档分类。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 6b9b585.

  • .github/workflows/frontstage-pages.yml: added README.ja.md next to README.zh-CN.md in both the pull_request and the push path lists.
  • scripts/ci/impact_plan.py: added README.ja.md to ROOT_DOCS, so a Japanese-only edit is classified as docs instead of full.
  • scripts/ci/test_impact_plan.py: new test_root_readme_locales_are_documents checks the three README-only inputs (README.md, README.zh-CN.md, README.ja.md; A/M/D each, and all three together) and expects docs. With the ROOT_DOCS change reverted, it fails on README.ja.md; with it, test_impact_plan.py passes (6 passed, 29 subtests).

This PR itself still runs full qualification because it touches scripts/ci/impact_plan.py, a policy path.

Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>
…EADME checks

Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max

评审 6b9b5852c7c6b7db9f490bb3a43540309d6f4828,Git 共同基点 8caf2da6a52d37f722703a02d79f9a70711b5bd1,另与当前主干 b48bd3b9202770cb0337ed2925cb646424c48fa2 核验集成。 上一头结论

动机 / Motivation

从 GitHub 仓库首页开始使用 LoopX 的日语读者,需要用同一语言查安装、启动、停止和恢复。 主干首屏提供英文和简体中文。候选在两页加入日本語入口,进入同一提交的日文快速开始和 Goal 生命周期说明。

英中入口都打开同一版日文页面,桌面和窄屏可跳到安装。日文单文件新增、修改和删除都归入文档范围并匹配原 Frontstage 检查。 本批范围为三份根 README、已有验证路径和文件分类。生命周期命令使用当前正式 CLI。

改动思路 / Approach

复用现有 README 的布局和启动流程,以一个日语页提供现行命令;将精确文件名加到现有验证和分类即可维护。 本 PR 交付日文上手路径、Goal 停止与恢复说明和单文件验证。原生命周期继续承接可执行操作。

只交付一张简短导航仍会让用户换语言阅读停止和恢复。完整译页复用原命令、公开资源和 Markdown 路径,日文修改沿用同一套检查。 README.md

具体改动 / Changes

上一轮两个反例已在实际入口分别复验。日文页的 Start with one goal 可从原两种语言的日本語链接进入;五问表后完整保留 Goal stop 的预览、恢复资格、owner 执行、已有状态指纹及独立 Core CLI。核对 43 个标题、9 个一致的命令块与 110 个可定位的本地目标,GitHub 返回的日文 15 个页内链接均可达。 日文操作 主干操作

Frontstage Pages 的 PR 与 main push 都包含日文文件,原构建继续运行 Star History 校验。分类器将单独新增、修改或删除日文文件视为 docs,与英中路径一致。 前台触发 文件分类

对主干的风险 / Risks

旧头的日文单文件错派 full 且缺原工作流匹配。候选的 A/M/D 矩阵恢复两条路径,混入产品代码或使用未登记的根文档名仍要求 full。9 项检查及 29 个子例、Star History 与标准预检的 5 项直接和 19 项选定通过。单独合入当前主干的三方集成干净。与 #8850 同时处理,两份根 README 的同一导航行会冲突,后续需要保留日本語入口与原可达的章节链接。

我的整体评价 / Verdict

桌面首屏可读日文介绍、语言链接和安装入口。窄屏正文正常换行,向下滚动可选择语言、进入安装段,命令仍在原有代码区块内。 本轮验证覆盖真实 GitHub 文件页、宽窄导航与仓库本地检查。托管运行结果和安装态交由原验收入口。

当前精确头补齐上一轮的两个问题,公开日语阅读路径和独立验证支持批准。 精确日文页

English verdict: APPROVE. The Japanese README preserves current Goal lifecycle guidance and Japanese-only updates reach the existing README validation.

@loopx-agent
loopx-agent merged commit f599a60 into loopx-project:main Nov 16, 2026
4 of 7 checks passed
huangruiteng added a commit that referenced this pull request Nov 17, 2026
* Prioritize new Lark replies over already attempted cards

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

* Isolate unreadable Lark reply scheduling hints

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

* fix: isolate agent settlement from peer semantic receipts (#8853)

Signed-off-by: huangruiteng <huangrt01@163.com>

* docs: add Japanese README (#8839)

* docs: add Japanese README

Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>

* docs: sync Japanese README with Goal lifecycle and route it through README checks

Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>

---------

Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>

* Retain unreadable Lark recovery hints until the next scan

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

---------

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: huangruiteng <huangrt01@163.com>
Signed-off-by: Ikko Eltociear Ashimine <eltociear@gmail.com>
Co-authored-by: huangruiteng <huangrt01@163.com>
Co-authored-by: Ikko Eltociear Ashimine <eltociear@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants