Bilingual Readme Sync

bilingual-readme-sync

Keep README.md and README.pt-BR.md structurally aligned in any repo that uses the 2-file bilingual pattern.

When to run

• After any edit to README.md in a repo that has a README.pt-BR.md sibling.
• After any edit to the canonical EN README in a repo pair (e.g. ai-dev-toolkit → mirror into ai-dev-toolkit-pt-br).
• Before release cuts, to guarantee the PT reader sees the same content the EN reader does.

Invariants

1. Line-count parity (±5%). A stub PT file next to a 300-line EN file is the trigger to ship a full translation.
2. Structural parity: same number of H1/H2/H3 headings, same table rows, same code blocks in the same order.
3. Language-switch header as line 1: [English](README.md) | [Português](README.pt-BR.md).
   • In a PT-primary repo (e.g. ai-dev-toolkit-pt-br): the English link points to the canonical EN repo URL, not a local file.
4. Code blocks, URLs, file paths, badges, shell commands: verbatim identical between EN and PT.
5. Technical terms kept in English: forge-kit, Claude Code, Codex, OpenCode, Cursor, Windsurf, GitHub Copilot, MCP, MIT, TypeScript, ESLint, CI, PR, skill/rule/agent/hook/pattern, skill names (loop, route, dispatch, tdd, secure, resume).

Diff heuristic (quick audit)

wc -l README.md README.pt-BR.md
# If the two differ by more than ~5%, parity is broken.

For a deeper audit, compare heading structure:

grep -c "^#" README.md README.pt-BR.md
grep -c "^##" README.md README.pt-BR.md
grep -c "^\`\`\`" README.md README.pt-BR.md  # code block openers

Workflow

Scenario A — EN-primary repo (e.g. ai-dev-toolkit)

1. Read current README.md and README.pt-BR.md.
2. If line-count parity is broken or new sections exist in EN but not PT, dispatch a translation subagent (see prompt template below).
3. Ensure both files start with:

   [English](README.md) | [Português](README.pt-BR.md)
   
   # <Title>
   

4. Commit as docs(readme): sync PT translation with EN.

Scenario B — PT-primary repo (e.g. ai-dev-toolkit-pt-br)

1. Pull canonical EN README from the EN repo; treat as source of truth.
2. PT repo's README.md is the PT version — mirror structure from canonical EN.
3. Language-switch header uses absolute URL for the EN link:

   [English](https://github.com/<org>/<en-repo>) | [Português](README.md)
   
   # <Título>
   

4. If repo currently has a redundant README.pt-BR.md (duplicate of README.md), git rm it.
5. Commit as docs: parity with <canonical-repo> README.

Scenario C — repo pair (EN canonical ↔ PT fork)

Do both A and B in one session. Use git worktrees so the two commits land on separate feature branches, one PR per repo.

Translation subagent prompt template

When dispatching a translation task to executor:

Translate the English README at <path> (<N> lines) to Brazilian Portuguese, and write the result to <destination>.

Rules:
- Preserve ALL code blocks verbatim (commands, JSON, file lists).
- Preserve ALL URLs, badge markdown, file paths.
- Preserve markdown structure (headings levels, tables, lists).
- Keep technical terms in English: forge-kit, Claude Code, Codex, OpenCode, Cursor, Windsurf, GitHub Copilot, MCP, MIT, ESLint, TypeScript, CI, PR, skill, agent, hook, rule, pattern, skill names.
- Translate: headings, body prose, table description columns, troubleshooting text.
- Start output with language-switch header (exact form depends on EN-primary vs PT-primary repo).

Include a curated "section title translations" table in the dispatched prompt so the subagent matches existing PT terminology.

Cross-repo propagation (ai-dev-toolkit ecosystem)

When shipping README changes in this ecosystem, update 3 locations:

1. ai-dev-toolkit/README.md + README.pt-BR.md (EN-primary)
2. ai-dev-toolkit-pt-br/README.md (PT-primary, points back to canonical EN repo)
3. ai-dev-toolkit-setup/README.md + README.pt-BR.md (independent, but same pattern)

All three must carry the language-switch header. Parity is ratcheted by running this skill after any README edit.

Non-goals

• This skill does not translate entire docs/ trees automatically. Use a separate translation pipeline for docs/guides/ etc. This skill is scoped to README parity.
• It does not lint prose quality or fix typos in existing translations — it only enforces structural + code-block parity.

Related

• spec-new — for larger content additions that warrant a spec record.
• aggregate-roadmap — for propagating roadmap state across repo pairs.