l-create-en-implementation

Create English translation implementation from the current branch's JA PR. Auto-detects the current branch's PR, creates an EN branch, translates MDX content, scaffolds EN routes if needed, and create...

Create EN Implementation from JA PR

Automate the full EN translation workflow: analyze a JA PR’s changes, translate MDX content, scaffold routes, and create a PR.

Input: None required. The user invokes this skill while checked out on the JA feature branch (e.g., topic/foo). The skill auto-detects the current branch’s PR.

Step 1: Parse PR Info

Detect the current branch and extract its PR metadata and changed files:

gh pr view --json headRefName,baseRefName,title,number,files
gh pr diff --name-only

If no PR is found for the current branch, inform the user and abort.

Save the head branch name (headRefName) — the EN PR will target this branch.

Step 2: Categorize Changed Files

Group the changed files from the PR into categories and report findings to the user:

MDX content (src/mdx/**/*.mdx, excluding .en.mdx)

• These need translation via the en-translator agent
• Check if an .en.mdx already exists for each file
• If .en.mdx already exists: Read both JA and EN files and compare section-by-section. The JA version may have been further edited after the EN was initially created. Identify which sections differ and flag them for re-translation. Pay special attention to opinion/impressions sections (e.g., “My Impressions” / “Takazudo的所感”) which are frequently rewritten by the user.

App routes (app/(ja)/**)

• Check if a corresponding EN route exists at app/(en)/en/
• New JA routes without EN counterparts need scaffolding

Components (components/**)

• Check if enComponents in components/mdx/mdx-provider.tsx needs updates
• New locale-aware components need EN wrappers with locale="en"

Data files (src/data/, lib/data/)

• Check for missing nameEn, labelEn, or descriptionEn fields
• New taxonomy entries (lib/data/taxonomy.ts) may need EN labels

Present the categorized findings to the user and wait for confirmation before proceeding.

Step 3: Create Branch

Create an EN branch from the JA PR’s head branch:

git fetch origin <headRefName>
git checkout -b <headRefName>/en origin/<headRefName>

Branch naming: <headRefName>/en (e.g., feature/new-guide/en)

Validate branch name length: Netlify limits total to 61 chars for takazudomodular project. Branch name must be ≤ 46 chars. If it exceeds this, abbreviate the topic portion and inform the user.

Step 4: Translate MDX Files

For each JA .mdx file that needs translation:

New files (no existing .en.mdx)

Use the en-translator agent:

Task tool → subagent_type: "en-translator"
prompt: "Translate <path-to-ja.mdx> to English. Write the result to <path-to-en.mdx>"

Updated files (existing .en.mdx)

Use the en-translator agent with both files:

Task tool → subagent_type: "en-translator"
prompt: "Update the translation at <path-to-en.mdx> based on changes in <path-to-ja.mdx>. Read both files, identify what changed in the JA source, and update only the corresponding sections in the EN file."

Already-synced files (existing .en.mdx with no JA changes in this PR)

Even if a JA file was not changed in this PR, its .en.mdx may still be out of sync if the EN was created in an earlier step and the JA was subsequently edited (e.g., user rewrote the impressions section). Always read and compare both JA and EN files for any MDX content touched by this workflow. If the EN doesn’t accurately reflect the current JA content, update it — either manually for small diffs or via the en-translator agent for larger changes.

Run translations in parallel when there are multiple files.

Step 5: Scaffold EN Routes (if needed)

Only when new JA routes were added with no EN counterpart.

Reference templates

• Notes: app/(en)/en/notes/[slug]/page.tsx
• Guides: app/(en)/en/guides/[slug]/page.tsx

Key patterns to follow

All EN route pages follow this pattern:

• Import from @/lib/articles/locale-utils (getArticleForLocale, get*SlugsForLocale)
• Import enComponents from @/components/mdx (not the default components)
• Import articleMdxOptions from @/lib/mdx/mdx-options
• Use locale="en" on ArticleLayout
• Set hreflang alternates in metadata:

  alternates: {
    languages: {
      ja: `/notes/${slug}/`,
      en: `/en/notes/${slug}/`,
    },
  },

• Use enComponents as MDX components:

  <MDXRemote source={content} components={mdxComponents} options={articleMdxOptions} />

Step 6: Handle Component/Data Updates (if needed)

New MDX components

If the JA PR added new MDX components that need locale awareness:

1. Check components/mdx/mdx-provider.tsx
2. Add locale-aware wrapper to enComponents object if needed:

   // In enComponents:
   NewComponent: (props: any) => <NewComponent {...props} locale="en" />,

New product/taxonomy data

If new products or taxonomy entries were added:

• Add nameEn / descriptionEn fields to product entries in src/data/product-master-data.mjs
• Add labelEn to new taxonomy entries in lib/data/taxonomy.ts

Step 7: Validate

Run the full check suite and fix issues:

pnpm check

If issues are found, fix with:

pnpm check:fix

Then re-run pnpm check to confirm all issues are resolved.

Step 8: Commit and Create PR

Commit

git add <translated-and-scaffolded-files>
git commit -m "[en] Add EN translations for <JA PR title>"

Create PR

The PR targets the JA PR’s head branch (not main). This way, when the JA PR merges to main, both JA and EN changes land together.

gh pr create \
  --base <headRefName> \
  --title "EN translations for #<number>: <JA PR title>" \
  --body "$(cat <<'EOF'
## Summary

- EN translations for JA PR #<number>
- Translated MDX files: <list>
- New EN routes: <list or "none">
- Component/data updates: <list or "none">

## Checklist

- [ ] All MDX files translated
- [ ] `pnpm check` passes
- [ ] EN routes render correctly (if new routes added)

## Related

- JA PR: #<number>

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Report the PR URL to the user when done.

Key Reference Files