sections localization

Localization (Japanese)

Active contributors: Andy Taylor, factory-droid[bot] (filtered from byline), francesca-factory

Purpose

docs/jp/ is a parallel Japanese tree that mirrors the English content file-for-file. Mintlify treats it as a separate language tab in docs/docs.json, and the Japanese sidebar is declared independently.

How it stays in sync

The repo runs two automation workflows that keep docs/jp/ aligned with English changes:

Workflow	When it runs
.github/workflows/sync-jp-docs.yml	On merges to main that touch English MDX files
.github/workflows/translate-jp-docs-bulk.yml	On manual dispatch — used for bulk translations and new sections

Both workflows invoke Factory's own droid (via the factory-droid[bot] GitHub identity) to perform the translation. They're a real-world example of droid-exec usage. The bulk workflow is much smaller (~1.5 KB); the per-PR sync workflow is significantly more complex (~13 KB) and includes guardrails for partial failure, conflict handling, and the supported PR-merged field that was patched in commit 4415896 ("fix: use supported PR merged field in JP sync workflow").

Coverage

• 121 Japanese MDX pages
• 125 English MDX pages

The 4-page gap is normal — it represents English pages added in the last day or two that haven't been synced yet. The bulk workflow can backfill if needed.

Navigation

docs/docs.json declares two languages: en and jp. The jp block defines its own tabs (ドキュメント, ガイド, 変更履歴, ベンチマーク, APIリファレンス) and group structure that mirrors — but is not auto-derived from — the English navigation. When new English groups are added, the JP groups must be updated too. This is the most common bug class for the JP side: a page exists at docs/jp/foo/bar.mdx but isn't listed in the JP nav block of docs.json, so it's unreachable from the JP sidebar.

Conventions

• Don't translate code, shell commands, or file paths. Keep <CodeGroup> blocks identical across languages.
• Keep frontmatter keys (title, description, keywords, sidebarTitle) identical — translate only the values.
• Mintlify component names (<Card>, <Note>, etc.) stay in English even when the rendered text is Japanese.
• Image references should point at the same files in docs/images/ — don't fork images per language.

Common edits

• Add a new English page → write it normally; the sync workflow handles the JP side after merge.
• Update an existing English page → same; the sync workflow re-translates the affected pages.
• Add a new section group → update both the en and jp blocks in docs.json. The sync workflow translates content but not navigation.
• Translate a manually-authored JP-only page → place it under docs/jp/ and add to the JP nav block.

Integration points

• The translation workflows use the same droid configuration referenced throughout the docs (skills, AGENTS.md). They are themselves the canonical "real-world" droid-exec deployment cited from the guides.
• The JP API reference tab points at the same OpenAPI spec as the English one but renders into a jp/api-reference directory.