# Zudo Doc Translate

> Translate zudo-doc documentation between English and Japanese with project-specific conventions.

- Skill: `takazudo/zudo-doc-translate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add takazudo/zudo-doc-translate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/takazudo/zudo-doc-translate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: takazudo (https://skillmd.com/u/takazudo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/takazudo/zudo-doc-translate

---


# zudo-doc Translation Skill

Translate documentation between English and Japanese following project-specific conventions.

## i18n Structure

This skill only applies when this project's i18n feature is enabled. A
non-i18n scaffold has no secondary-locale content directory (e.g. no
`docs-ja/`) and no locale-prefixed routes — there's nothing to translate.
Check `zfb.config.ts`'s `zudoDoc({...})` call: if it sets a non-empty
`locales` field, i18n is on.

- Default-locale docs: `src/content/docs/` — routes at `/docs/...` (the
  default locale is never prefixed)
- Secondary-locale docs: `src/content/docs-<locale>/` — routes at
  `/<locale>/docs/...`. For the common preset (English default, Japanese
  secondary) this is `src/content/docs-ja/` at `/ja/docs/...`; the rest of
  this skill assumes that pairing, but confirm the actual locale code and
  directory from `zfb.config.ts` if this project uses a different one
- Directory structures must mirror each other exactly (same filenames, same folder hierarchy)
- Locale configuration lives in this project's `zfb.config.ts`, inside the
  `zudoDoc({...})` call: `defaultLocale` (the default locale code — always
  unprefixed, no separate flag needed) and `locales` (a map of additional
  locale code → `{ label, dir }`; each entry becomes a `/<code>/docs/...`
  route tree)

## Translation Rules

### Keep in English (do NOT translate)

- Component names: `<Note>`, `<Tip>`, `<Info>`, `<Warning>`, `<Danger>`, `<Tabs>`, `<TabItem>`, `<Details>`
- Code blocks — code is universal
- File paths: `src/content/docs/...`, `.claude/skills/...`, etc.
- CLI commands: `<pm> run dev`, `<pm> run build`, etc. (`<pm>` = this project's package manager)
- Technical terms that are standard in English (e.g., component, props, frontmatter, slug)
- Frontmatter field keys (`title`, `description`, `sidebar_position`, `category`)

### Translate

- Frontmatter field values (e.g., the `title` value, the `description` value)
- The `title` prop of admonition components (e.g., `<Note title="注意">`)
- Prose content, headings, list items, table cells (except as noted below)

### Table conventions

- In tables with a "Required" column: use **"Yes"** / **"No"** directly, NOT "はい" / "いいえ" — Japanese conversational yes/no is unnatural in technical documentation

### Internal links

- Adjust link paths when translating:
  - En→Ja: `/docs/getting-started` → `/ja/docs/getting-started`
  - Ja→En: `/ja/docs/getting-started` → `/docs/getting-started`

## File Naming

- Japanese files use the **same filenames** as English (e.g., `writing-docs.mdx`)
- Only the parent directory differs: `docs/` vs `docs-ja/`
- Example: `src/content/docs/guides/writing-docs.mdx` → `src/content/docs-ja/guides/writing-docs.mdx`

## Workflow

### En→Ja Translation

1. Read the English source file from `src/content/docs/`
2. Check if the corresponding Japanese file already exists in `src/content/docs-ja/`
   - If it exists, read it first — use it as a base and update from the English source rather than overwriting from scratch
   - If it does not exist, create the file at the equivalent path in `src/content/docs-ja/`
3. Translate the content following the rules above
4. Verify internal links point to `/ja/docs/...`

### Ja→En Translation

1. Read the Japanese source file from `src/content/docs-ja/`
2. Check if the corresponding English file already exists in `src/content/docs/`
   - If it exists, read it first — use it as a base and update from the Japanese source rather than overwriting from scratch
   - If it does not exist, create the file at the equivalent path in `src/content/docs/`
3. Translate the content following the rules above
4. Verify internal links point to `/docs/...` (no `/ja/` prefix)

### Post-Translation Checks

- Frontmatter keys are unchanged (only values translated)
- All admonition component names remain in English
- Code blocks are untouched
- Internal links use the correct locale prefix
- Directory structure mirrors the source language