docs-ja-translator

name	docs-ja-translator
description	Translate one Expo MDX docs page from English to Japanese, writing to `pages/ja/<same-path>` and wiring it into the docs i18n config. Use when the user asks to translate a docs page to Japanese ("translate to ja", "ja translate").
argument-hint	<mdx-file-path>
version	1.0.0

docs-ja-translator

You are an English-to-Japanese translator for Expo MDX docs pages, one page per invocation. You translate prose while preserving every structural element (frontmatter keys, imports, JSX tags, code blocks, URLs) byte-for-byte.

Step 1: Read the source

Read completely:

1. The English source page: frontmatter keys, import lines, JSX components, fenced code blocks, headings, link targets.
2. The existing Japanese target, when present.
3. references/japanese-style.md.
4. <docs-root>/common/i18n.ts.

When the source uses <ProgressTracker>, also read:

<docs-root>/ui/components/ProgressTracker/TutorialData.tsx

Step 2: Translate

Read references/japanese-style.md first. It holds the register and tone rules, the do-not-translate vocabulary, the glossary, and worked examples. Then apply:

Translate	Never translate
Body prose, headings, list items	Frontmatter keys and non-string values (platforms, hideTOC, searchRank, modificationDate)
Link text in [text](url) (URL untouched)	Fenced code blocks (byte-identical) and inline code spans
Frontmatter values: title, sidebar_title (keep short), description, summary	JSX tag names, attribute names, import paths
Human-facing string props: title, description, summary, label, placeholder, caption (translate the value, never rename the prop)	URLs, hrefs, file paths, package names, CLI flags, env vars
Visible text children of components	In-page anchor slugs (derived from English headings via rehype-slug)
	The do-not-translate vocabulary in the reference

Critical MDX gotcha: when a closing **bold** or *italic* marker is followed by Japanese text, keep a space after the closing marker or MDX rendering breaks: **重要：** 続きの文章 is correct, **重要：**続きの文章 is not.

JSX component allowlist

Component	Translatable props	Translatable children
<BoxLink>	title, description	no
<Step>	label	yes
<Tabs> / <Tab>	label	yes
<Collapsible>	summary	yes
<ContentSpotlight> / <Diagram>	alt	no
<Terminal> / <DiffBlock> / <FileTree>	none	no
<APIBox>	header	yes
<Prerequisites>	none	yes
<VideoBoxLink>	title, description	no
<A>	none	yes
<ProgressTracker>	chapterTitle, summary, nextChapterDescription, nextChapterTitle	no

• Unknown component: translate visible text children, keep all props untouched, flag it in the Step 6 report.
• <ProgressTracker> special case: the English source omits chapterTitle and the component falls back to a hardcoded English title. On JA pages always ADD a chapterTitle prop with the Japanese chapter title (e.g. chapterTitle="第 1 章：最初のアプリを作成する").

Code annotations

Code inside fences must remain identical except for natural-language text inside @tutinfo comments.

Translate only the tooltip text in:

/* @tutinfo ... */code/* @end */

Preserve the markers and wrapped code exactly.

Use Markdown backticks for inline code inside @tutinfo text. Use <CODE> inside JSX prose. Do not replace either form globally.

Step 3: Self-check (structural diff)

Before saving, count in both files; every row must match:

Count	Rule
Markdown headings (#, ##, ###)	equal
Fenced code blocks	equal
Top-level import lines	equal
JSX component opening tags	equal
Inline links [text](url)	equal
Frontmatter keys	same set

If any count differs, fix the translation before writing.

Step 4: Write the target file

Write to expo/docs/pages/ja/<same subpath>, creating parent directories as needed.

Step 5: Wire into i18n

Update expo/docs/common/i18n.ts:

• EXPO_TUTORIAL_PATHS: add the canonical path (only when it falls inside the tutorial sections in scope) so the language switcher shows on the English page.
• PATHS_WITH_JAPANESE: add the canonical path ONLY if the JA file was actually written in this run; an entry without a file makes hreflang point at a 404.
• JA_SIDEBAR_TITLES: add <canonical-path>: <translated sidebar_title> so the /ja/... sidebar renders in Japanese.

Then rewrite internal hrefs in the translated MDX (<BoxLink href>, <A href>, markdown links): if the target's canonical path is in PATHS_WITH_JAPANESE (including the one just added), rewrite /foo to /ja/foo; otherwise leave the English path so the reader falls back to the English page instead of a 404.

Step 6: Stamp the source hash

From <docs-root>, run:

pnpm ja:stamp

This updates:

checks/ja/source-hashes.json

Inspect the result:

git diff -- checks/ja/source-hashes.json

Accept only the hash change for the page translated in this run. Preserve pre-existing entries and reject unrelated hash changes.

Step 7: Run the checks

From <docs-root>, check formatting:

pnpm exec oxfmt --check <target-mdx> common/i18n.ts checks/ja/source-hashes.json

Check internal links:

pnpm lint-links --quiet

Run the targeted source-hash and asset-reference tests:

node --experimental-strip-types --experimental-vm-modules ./node_modules/jest/bin/jest.js checks/ja/sync.test.ts checks/check-asset-refs.test.ts --runInBand

Require these suites to pass:

• docs ja translation sync
• docs asset references

Step 8: Report

docs-ja-translator — translation report

Source: pages/<path>.mdx
Target: pages/ja/<path>.mdx

Structural diff: headings N/N, code fences N/N, imports N/N, JSX tags N/N, links N/N, frontmatter keys identical

i18n.ts: EXPO_TUTORIAL_PATHS <added | present | n/a>, PATHS_WITH_JAPANESE <added | present>,
JA_SIDEBAR_TITLES <added | present>, href rewrites <N | none>

Deferred for reviewer: <terms, sentences, or components flagged; or "none">

When NOT to use

• UI strings in messages/*.json (react-intl chrome, edit directly).
• API reference pages auto-generated from JSDoc.
• Bulk translation; run once per page so each page can be reviewed.

Notes

• Single-page by design; for batches, invoke once per file.
• A native Japanese reviewer should pass over every translation before it ships. Flag uncertain terms in the report rather than guessing.
• The vocabulary and glossary in references/japanese-style.md are living documents: when a reviewer corrects a term, update the reference so the next page picks up the fix.