docs: English-first outward documentation, bilingual README and kit - #22
Merged
Conversation
The kit is the one outward-facing set of docs that non-developers read, so it keeps a Chinese translation. Everything else outward-facing becomes English only; CLAUDE.md and docs/internal/ stay Chinese because their only readers are maintainers and a second copy would just drift. en/ carries real content rather than placeholders pointing at zh/, so no page promises a translation it does not have. Cross-links inside the kit are sibling-relative, so moving the eight pages into zh/ left them resolving unchanged; only the four links from outside the kit and one parent-relative link needed rewriting. English terminology follows frontend/src/i18n.tsx rather than a second glossary invented here -- that file is what the product's own UI says, and a doc that disagrees with the UI is worse than one that reads awkwardly. scripts/check-docs.py enforces both halves of this: relative links resolve, and English-only docs contain no Chinese. Neither go vet nor the frontend build reads Markdown, so without it a file move silently breaks links on main.
Two claims did not survive being re-read against the code, so they are corrected rather than translated forward: The "current status" section required a preinstalled Python 3.12 for Aider. internal/install/install.go:229 says the opposite -- uv resolves the interpreter and downloads a managed CPython into ~/.oneagent/runtimes/python when the machine has none, which is why that prerequisite was dropped. The guide-only list named nine agents. agents.lock.json holds eight entries total, of which three are guide-only (Cursor, OpenClaw, Hermes); the other six names referred to catalog entries that no longer exist. Also removed the "public website" build block: site/ is not tracked in this repository any more (it moved to MaimoryLab/OneAgent-site), so `cd site` only worked for someone with stale build output on disk.
Eight of the nine were Chinese; ADR-007 was already English and set the register. Section headings were already English across all nine, so only the H1 titles and the prose changed and no structure moved. The supersession graph is what makes this directory worth keeping, so it was checked rather than assumed: ADR-003 superseded by ADR-007 for the Python core, ADR-006's credential delivery superseded by ADR-008, ADR-009 partially superseded with its renumbering note intact (it was originally a second ADR-006, and ADR-008's Supersedes line points at the other one). Two contradictions surfaced during translation and were deliberately left as found, because resolving them would change a decision rather than translate it: ADR-003's header still cites cmd/oneagent-release as authoritative while its own addendum records the tool's removal, and ADR-005 describes a verification stage owned by that same deleted binary. ADR-008's claims were verified against the code before translating: write.go writes requires_openai_auth and auth_mode = apikey, internal/config/env.go is gone, and credential_delivery no longer appears in agents.lock.json.
product-boundary-baseline.md, distribution-compliance-policy.md, and public-site-operations.md. These gate releases, so structure was verified rather than eyeballed: 17 and 15 unchecked checklist boxes before and after, none ticked, heading and list counts unchanged, and the telemetry field fence byte-identical. Absolute prohibitions stay absolute. One line drifted and was corrected: the `curl | bash` rule had been rendered as "is not executed", which reads as conditional permission next to the neighbouring bullet's "are prohibited" for the same class of risk. The one Chinese-prose code fence, the activation flow in section 6.1, is translated; the fence holding telemetry identifiers is not, since those are field names rather than prose. public-site-operations.md keeps its warning that the two workflows it was written around no longer exist, so nobody follows an obsolete release sequence.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #21.
Outward-facing documentation becomes English. The two places a Chinese reader needs are kept: the README and the AI Agent Kit.
CLAUDE.mdanddocs/internal/stay Chinese, because their only readers are maintainers and a second copy would just drift.What changed
README.mdREADME_ZH.mdalongsidedocs/specificationsdocs/decisions/(9 ADRs)docs/ai-agent-kit/en/+zh/, both completeCLAUDE.md,docs/internal/The kit's
en/pages carry real content rather than placeholders pointing back atzh/, so no page promises a translation it does not have.Two facts made this smaller than it looked: ADR section headings (
## Status,## Context,## Decision,## Consequences) were already English in all nine files, so no structure moved; and the English terminology comes fromfrontend/src/i18n.tsxrather than a glossary invented here, since that file is what the shipped UI says and a doc disagreeing with the UI is worse than one that reads awkwardly.Four stale claims corrected rather than translated forward
Translating these as-is would have carried errors into a second language.
internal/install/install.go:229says the opposite: uv resolves the interpreter and downloads a managed CPython into~/.oneagent/runtimes/pythonwhen the machine has none.agents.lock.jsonholds eight entries total, three of them guide-only (Cursor, OpenClaw, Hermes). The other six named catalog entries that no longer exist.cd sitebuild block.site/is untracked here (0 tracked files) since the move toMaimoryLab/OneAgent-site; the block only worked for someone with stale build output on disk.curl | bashrule read as conditional permission after translation, next to a neighbouring bullet using "are prohibited" for the same class of risk. Tightened to match.Two contradictions deliberately left as found
Resolving these would change a decision rather than translate one, so they are preserved and reported instead:
cmd/oneagent-releaseas authoritative while its own addendum records that the tool was removed.ADR relationships verified, not assumed
The supersession graph is why this directory exists, so it was checked after translating: ADR-003 superseded by ADR-007 for the Python core, ADR-006's credential delivery superseded by ADR-008, and ADR-009 partially superseded with its renumbering note intact (it was originally a second ADR-006, and ADR-008's
Supersedesline points at the other one).ADR-008's security constraints were checked against the code:
write.gowritesrequires_openai_authandauth_mode = "apikey",internal/config/env.gois gone, andcredential_deliveryno longer appears inagents.lock.json. Its 0600 handling, atomic write order, and refuse-to-write-on-JSONC rule all survived translation intact.Release checklists were counted rather than eyeballed: 17 and 15 unchecked boxes before and after, none ticked.
New gate
scripts/check-docs.pyverifies that relative links resolve and that English-only documents contain no Chinese, wired intoci.ymlas a third job. Neithergo vetnor the frontend build reads Markdown, which is how a file move silently breaks links on main — this PR moved eight files and the checker caught four stale links from outside the kit.Verification
Noted, not addressed
docs/status-dot-ui-plan.mdis an unimplemented plan sitting atdocs/root, which contradicts the layering rule that plans belong in issues. Out of scope here.MaimoryLab/OneAgent-sitestill hasdefaultLocale: "zh-CN", the opposite of this direction. It is a separate repository on its own release cadence, so that is a separate decision.translate()consults the table only whenlocale === "en"). Documentation and UI now differ in source-language direction;CLAUDE.mdrecords this so nobody "finishes the job" by rewriting the 315 i18n keys.🤖 Generated with Claude Code