Claude Skills Guide

Claude Code Translate Code Comments Between Languages

When you inherit a codebase written in a language you don’t fully understand, code comments become your lifeline. But what happens when those comments are in a language you cannot read? This is a common scenario in global development teams, open-source projects with international contributors, and legacy systems maintained across generations of developers. For localization automation workflows, see Claude Skills for Localization i18n Workflow Automation.

Claude Code provides several approaches to translate code comments between languages. This guide covers practical methods ranging from simple one-off translations to systematic translation workflows.

Using Claude Code Directly for Comment Translation

The most straightforward approach uses Claude Code’s built-in capabilities. When you share a code file with Claude, you can request translation of all comments:

Read this file and translate all comments from Japanese to English. Preserve the code itself.

Claude analyzes the file, identifies comments (both line comments // and block comments /* */), and provides translated versions while keeping the code intact.

For more control, you can specify exactly what you need:

Extract all Chinese comments from this Python file and provide English translations. Show the original and translated versions side by side.

This approach works with any programming language since Claude recognizes comment syntax across dozens of languages.

Systematic Translation Workflow for Large Codebases

For projects with hundreds of files, a systematic approach saves time. Create a dedicated translation skill to handle recurring translation tasks.

Step 1: Create a Translation Skill

Store this in ~/.claude/skills/translate-comments.md:

# Translate Code Comments

You help translate code comments between languages while preserving code integrity.

When asked to translate comments:
1. Identify all comment types (line, block, documentation)
2. Translate content accurately, preserving technical terminology
3. Keep code unchanged
4. Use natural language in target language
5. Preserve formatting and indentation

For multi-file projects:
- Process files sequentially
- Report translation count per file
- Note any ambiguous terms requiring human review

Step 2: Apply to Multiple Files

With the skill active, process entire directories:

Translate all Japanese comments in the /src directory to English. Output a summary of files processed and any terms that need clarification.

Claude processes each file systematically, maintaining the translation skill’s guidelines for consistency.

Handling Documentation Comments

Documentation comments (Javadoc, JSDoc, docstrings) require special attention since they often contain more detailed explanations than inline comments.

Python Docstring Translation Example

Original:

def calculate_metrics(data: list[float]) -> dict:
    """
    Calcola le metriche base per il dataset fornito.
    
    Args:
        data: Lista di valori numerici
        
    Returns:
        Dizionario contenente media, mediana e deviazione standard
    """

Translation request:

Translate this docstring from Italian to English, maintaining the parameter documentation format.

Result:

def calculate_metrics(data: list[float]) -> dict:
    """
    Calculates basic metrics for the provided dataset.
    
    Args:
        data: List of numerical values
        
    Returns:
        Dictionary containing mean, median, and standard deviation
    """

Combining with Other Claude Skills

The translation workflow becomes more powerful when combined with other Claude skills.

Pair with the docx Skill for Documentation

When translating comments reveals the need for updated documentation, the docx skill helps maintain external docs:

Use the docx skill to update the API documentation with the new English comments from the codebase.

Pair with the frontend-design Skill for UI Comments

If your codebase contains UI-related comments (button labels, error messages, tooltips), the frontend-design skill ensures translated strings are properly integrated into your interface:

The frontend-design skill should review the translated strings to ensure they're suitable for display in the user interface.

Pair with the pdf Skill for Legacy Documentation

When translating code reveals references to legacy PDF documentation, the pdf skill helps cross-reference:

The pdf skill should check if the referenced documentation still exists and update links accordingly.

Best Practices for Code Comment Translation

Preserve Technical Terms

Technical terms should remain in their original form when universally understood:

// Original (German)
// Initialisiere den HTTP-Client mit timeout von 5000ms

// Translated
// Initialize HTTP client with 5000ms timeout

Terms like “HTTP,” “timeout,” “callback,” and “API” stay in English even when translating surrounding comments.

Handle Ambiguous Terms

When translation might alter meaning, flag for human review:

Note: The term "Zeiger" could mean "pointer" (C programming) or "hand" (UI). Interpreted as "pointer" based on context.

Maintain Comment Position

Always keep comments in their original positions relative to code:

// BAD: Moving comment below code
int result = calculate(); // Calculate the result first

// GOOD: Preserving original position
// Calculate the result first
int result = calculate();

Automating Translation with Claude Code Hooks

For ongoing projects with multilingual contributors, consider using Claude Code hooks to standardize comment language.

Create a pre-commit hook that identifies non-English comments:

# .git/hooks/pre-commit
# Check for non-English comments (example for Python)
grep -n "#" --include="*.py" *.py | grep -v "^[0-9]*:.*#" | head -20

Trigger Claude to translate when new non-English comments are detected:

Run translate-comments skill on recently modified files to ensure all new comments are in English.

Common Challenges and Solutions

Multi-line Block Comments

Block comments spanning multiple lines require careful handling:

/* Diese Funktion behandelt die Benutzerauthentifizierung
 * durch Validierung der Anmeldeinformationen gegen die
 * Datenbank. Gibt true bei erfolgreicher Authentifizierung
 * zurück, false otherwise.
 */

Claude handles these by translating each line while preserving the comment structure.

Comment-Embedded Code Examples

When comments contain code examples, translate explanations but preserve the code:

# Example: loop through items
# 示例：循环遍历所有项目
for item in items:
    process(item)

The code stays unchanged; only the surrounding explanation translates.

Cultural References and Idioms

Idioms don’t translate directly. Claude provides contextually appropriate equivalents:

// Original: "Das ist ein Kinderspiel" (German)
// Translation: "This is a piece of cake" (not "This is a children's game")

Conclusion

Translating code comments with Claude Code transforms unreadable code into maintainable assets. Whether you need one-time translations or systematic workflows, Claude adapts to your project’s needs.

For quick translations, direct interaction works best. For ongoing projects, create dedicated skills and consider hook automation. Combine with other skills like docx, pdf, and frontend-design for comprehensive documentation workflows.

Start with a single file to establish your translation pattern, then scale to entire codebases. The key is consistency—establish conventions for technical terms, maintain comment positions, and flag ambiguous translations for human review.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides