Proposal: where should community translations live? (starting with Japanese)

[eltociear]

I've translated the root README.md and CONTRIBUTING.md into Japanese. The files are on a branch in my fork: https://github.com/eltociear/deepseek-harness/tree/add-ja-doc

I'm not opening a pull request — CONTRIBUTING.md says external PRs can't be accepted right now, so I'm raising it here instead, as that document suggests.

I don't think "merge two files" is the real question, though. Reading docs/i18n/README.md, the documentation system looks bilingual by construction rather than multilingual with two languages configured:

• a pair is three sibling files (foo.md, foo.zh.md, foo.i18n.yaml), and the consistency record holds exactly two blob hashes
• verify-translation-pairing, the dsh-translation-pairing merge driver, and translation-prompt.ts's two render directions all assume two sides
• the website projects two locales
• the docs are explicit that the gate cannot judge whether two sides actually say the same thing — that half of the contract belongs to a reviewer who reads both languages

So a third language isn't a file addition; it's a change to the contract, and it needs someone on the review side who reads it. That's a real cost, and it's yours to weigh rather than mine. Three ways it could go, cheapest first:

1. A community-translations carve-out. Japanese files live outside the pairing gate entirely — explicitly community-maintained and unverified, excluded through the existing manifest mechanism, reachable by a single link. The pairing contract is untouched and nothing in CI learns a third language. The cost is a manifest entry and the honesty of the "unverified" label.

2. Generalize pair → set. .i18n.yaml records N hashes, switchers list N languages, the structural signature is checked per language, the website gains a locale. Correct, and much larger — and probably not worth doing for one language without a maintainer per language.

3. Not now. The Japanese docs stay in a separate community repo with no official link. This is my default if there's no appetite, and it's a fine answer.

Either way, I'm offering to maintain the Japanese side and keep it in sync with the English source, following terminology.md and translation-rules.md.

If the answer is (3), no reply is needed — I'll read the absence of interest as the answer and won't push it further. Mainly I'd like to avoid doing work that has nowhere to go.

[Electricitysheep]

Good question. We faced the same in the dsh-handbook project - our approach: keep the Chinese README as canonical, maintain README.en.md (full sync, not translation lag), and translate the 12+ chapters to English (.en.md files side by side with Chinese). Each language has a switch link at the top.

For the official repo, I'd suggest: translations in a /translations dir or per-file .ja.md / .zh.md siblings, with a language-switch bar in the README (like awesome-deepseek-agent does). Happy to share our sync workflow (we run consistency checks between README.md and README.en.md): https://github.com/Electricitysheep/dsh-handbook

[eltociear]

Thanks @Electricitysheep! The .ja.md sibling + language-switch-bar pattern is actually already this repo's convention — the .zh.md pairs work exactly that way, so the Japanese files follow it out of the box (README.ja.md / CONTRIBUTING.ja.md ship with the switcher).

So the real open question here is the verification contract, not the file layout. I checked the verifier: its scope is English↔Chinese only —

const README_ARTIFACT = /(?:^|\/)readme(?:\.md|\.zh\.md|\.i18n\.yaml)$/i

.ja.md matches none of those branches, so README.ja.md is out of isTranslationScopeFile. Practical consequence: the JA files don't break verify-translation-pairing (this branch adds only the two JA files and leaves the EN↔ZH pair — and its recorded blob hashes — untouched, so CI stays green), but they also get no drift check and no bilingual-reviewer gate. In other words, Option 1 (unverified community carve-out) is effectively the default today.

That's exactly why your consistency-check offer is the interesting part — I'd love to see it. An automated README.ja.md ↔ README.md freshness check (flag when the English source moves but the JA sibling hasn't) would give the JA docs an automated substitute for the human bilingual review the ZH pair relies on, without forcing the pair→set generalization in Option 2.

@maintainers — two things I'd want a steer on before opening a PR:

1. Discoverability: should the canonical README.md (and README.zh.md) switcher gain a 日本語 link? That edits the EN↔ZH pair and needs a hash re-record on both sides, so I don't want to do it unasked.
2. Whether you'd accept a lightweight JA drift-check in CI, or prefer JA stays a fully unlinked community file for now.

Happy to open the PR either way once you point me at the shape you want.

[Electricitysheep]

Good point — the .ja.md sibling pattern already matching this repo's convention means the layout question is settled; the real gap is the verification contract (EN↔ZH only, so .ja files won't be checked).

For dsh-handbook we faced the same sync problem: we keep README.md ↔ README.en.md in sync via manual consistency checks (numbers/links/structure) each iteration, and the 14 chapters have .en.md siblings. It's labor but it catches drift early. If you extend the verifier to .ja (or make the artifact regex configurable), the pattern would scale to any language — that's probably worth a small RFC.

[eltociear]

"Make the artifact regex configurable" was my first instinct too, so I went and ran the real modules against it. The regex turns out not to be the gate for most of the tree, and changing it does something other than what it looks like.

1. A .ja.md under docs/, python/, or .agents/notes/ is already in scope today — no regex change required. isTranslationScopeFile is a disjunction, and the two artifact regexes only cover the root README/CONTRIBUTING; everything else enters by path prefix:

return !file.startsWith('.agents/notes/archived/')
  && !isTranslationSourceExcluded(file) && (README_ARTIFACT.test(file)
  || ROOT_CONTRIBUTING_ARTIFACT.test(file)
  || file.startsWith('.agents/notes/')
  || file.startsWith('docs/')
  || file.startsWith('python/'))

Calling it directly on candidate paths:

README.ja.md                   in-scope=false
CONTRIBUTING.ja.md             in-scope=false
docs/i18n/README.ja.md         in-scope=true
docs/guide.ja.md               in-scope=true
python/sdk/README.ja.md        in-scope=true
.agents/notes/x.ja.md          in-scope=true
apps/web/README.ja.md          in-scope=false
translations/README.ja.md      in-scope=false

2. In scope does not mean "checked as a translation" — it means "classified as a source." The split is by suffix, not by the artifact regex:

const translations = [...files].filter(f => f.endsWith('.zh.md')).sort()
const sources = [...files].filter(f => f.endsWith('.md') && !f.endsWith('.zh.md')).sort()

.ja.md is not .zh.md, so it lands in sources, and rule 1 of the check then demands a Chinese counterpart for it:

docs/guide.ja.md: in-scope documentation must merge bilingual (docs/i18n/README.md); add the counterpart and record the pair

and translationPairPaths('README.ja.md') returns

{"source":"README.ja.md","zh":"README.ja.zh.md","meta":"README.ja.i18n.yaml"}

So extending the artifact regex to .ja would not register Japanese as a third language. It registers Japanese as a new English that owes its own Chinese translation.

3. The consistency record cannot absorb a third hash either. parseTranslationPairingRecord rejects on arity:

if (hashes.size !== 2 || sourceHash === undefined || zhHash === undefined) return undefined

Adding a README.ja.md: <hash> line to an existing sidecar makes the record malformed, not extended — I ran it: two entries parse, three return undefined, and the check reports it as a malformed record rather than an extra language.

All three fail closed, which is the correct behaviour. But it means the knob isn't the regex: it's the source/translation classifier, translationPairPaths, and the record arity, and it has to be all three together. That is Option 2 from the opening post, and it's a genuine RFC rather than a config flag — worth writing only with a maintainer per language behind it, which is the one thing I can't supply by myself.

The practical consequence, which I hadn't stated precisely enough before: community JA files have to live outside docs/, python/ and .agents/notes/, or CI breaks — not because anyone excluded them, but because the path prefix pulls them in as sources. The repo root is one such place, which is where my branch already has README.ja.md and CONTRIBUTING.ja.md. The /translations directory you suggested upthread is another, and verifies as out of scope too — a tidier home if the maintainers would rather the root stayed clean. Either way that is Option 1, working today, with zero change to the pairing contract.

On your manual numbers/links/structure check: the encouraging part is that this repo already has that half as code, and it's language-agnostic. translationStructureSignature / translationStructureDiff compare headings by depth, code blocks, table row×column counts, list shape, and link targets in order — none of which knows anything about Chinese. A JA drift check could call those two functions directly and stay entirely out-of-band from verify-translation-pairing: no third hash, no scope change, no new language in the gate. That is small enough that I'd just write it once the JA files have a home.

@maintainers — the two questions from my previous comment stand, and this narrows the second one: a JA drift check does not require extending the pairing gate, and I'd argue it shouldn't.