Translation Skill

Translate documentation files between English and Japanese while maintaining technical accuracy and consistency with existing translations.

Guidelines

Translation Glossary

IMPORTANT: Before starting translation, read the complete translation glossary:

• •File: .claude/skills/translate/glossary.md
• •Terms: 56 software development terms including:
  • •Container technology: Docker, Podman, OCI, K8s, image, volume, daemon, etc.
  • •DevOps/CI/CD: GitHub Actions, workflow, pipeline, deployment, PR, etc.
  • •General software development: API, CLI, SDK, library, framework, dependency, etc.

Software Development Terms

When translating software development terms:

1. •Acronyms: Keep acronyms in English (API, CLI, SDK, OCI, K8s)
2. •Proper nouns: Keep proper nouns unchanged (Docker, Podman, GitHub, Kubernetes)
3. •Technical terms: Use glossary translations (workspace → ワークスペース, container → コンテナ)
4. •Code-related: Keep code identifiers, variable names, and command names in English

Translation Rules

1. •

   Code blocks: Keep identical (no translation)

   • •Bash scripts, YAML, JSON, code examples must be unchanged
   • •Comments in code blocks may be translated if appropriate
2. •

   Links and URLs: Preserve exactly

   • •Update relative links if pointing to language-specific files
   • •Example: README.md → README.ja.md in language selector links
3. •

   Section headings: Translate consistently

   • •Use existing translations from parallel documentation as reference
   • •Maintain heading hierarchy (same number of #)
4. •

   Code identifiers: Keep unchanged

   • •File paths, variable names, function names, command names
   • •Example: provider.yaml, PODMAN_MACHINE_NAME, devpod up
5. •

   Technical abbreviations: Keep in English with Japanese explanation if needed

   • •Good: "OCI (Open Container Initiative)"
   • •Bad: "オーシーアイ"

File Structure

Maintain identical structure between English and Japanese versions:

• •Same section ordering
• •Same heading hierarchy
• •Same code examples (identical)
• •Same links (update paths only if pointing to language-specific content)

Quality Checklist

Before considering the translation complete, verify:

• • All technical terms match the glossary
• • Code blocks are identical in both versions
• • Links are functional in both versions
• • Language selection links point to correct files
• • Section structure matches between versions
• • Acronyms and proper nouns are preserved correctly

Task

Translate the file specified in the arguments from the source language to the target language.

Arguments:

• •$ARGUMENTS[0]: Filename to translate (e.g., README.md)
• •$ARGUMENTS[1]: Source language code (en or ja)
• •$ARGUMENTS[2]: Target language code (en or ja)

Steps

0. Validate language codes

Validate the language code arguments:

• •$ARGUMENTS[1] (source) must be en or ja
• •$ARGUMENTS[2] (target) must be en or ja
• •If invalid, display error message with usage example

Language code mappings:

• •en: English
• •ja: Japanese (日本語)

1. Read source file

Use the Read tool to read the complete source file.

• •Identify all sections and their content
• •Note code blocks, links, and special formatting
• •Identify the file structure

2. Load translation glossary

Read the translation glossary to ensure terminology consistency:

• •File: .claude/skills/translate/glossary.md
• •Pay attention to software development terms
• •Note any special translation rules

3. Plan translation approach

Before editing, explain your approach:

• •Identify technical terms that should use the glossary
• •Identify sections that have parallel translations in existing files
• •Plan how to maintain structure
• •Note any links that need path updates

4. Perform translation

Create or edit the target file:

• •Maintain identical structure to source
• •Use consistent terminology from glossary
• •Preserve all code examples without changes
• •Keep all links (update paths only if language-specific)
• •Maintain all formatting (bold, italic, lists, tables)

Target filename:

• •en → ja: Add .ja before extension (e.g., README.md → README.ja.md)
• •ja → en: Remove .ja from filename (e.g., README.ja.md → README.md)

5. Verification

Check the translation quality:

• • All code blocks are identical to source
• • Section structure matches source exactly
• • Technical terms are consistent with glossary
• • Links are appropriate for the target language
• • Language selector links are updated
• • No untranslated sections remain (except code)

6. Report

Provide a summary of the translation:

• •Source file and target file paths
• •Number of sections translated
• •Notable technical terms used
• •Any manual review recommendations

Examples

For detailed examples of expected translation quality, see examples.md.