Code Translation

Code Translation

Systematic translation of code between programming languages while preserving correctness, adapting to idiomatic conventions of the target language, mapping library equivalents, handling type system differences, and verifying the translation through testing. This skill covers both small snippet translations and large-scale project migrations.

When to Use This Skill

Use this skill for:

• Porting a module or library from one language to another
• Converting code examples from documentation written in a different language
• Migrating a project from one technology stack to another (e.g., Java to Kotlin, Python 2 to Python 3, JavaScript to TypeScript)
• Adapting an algorithm implementation from a reference language to your project's language
• Translating test cases alongside production code
• Creating polyglot implementations that must behave identically across languages

Trigger phrases: "translate this code", "port to Python", "convert to JavaScript", "rewrite in Java", "translate from", "code migration", "language conversion", "port this function", "equivalent in", "same thing in Python"

What This Skill Does

This skill provides a structured translation methodology:

• Language Mapping: Maps constructs, keywords, and idioms from the source language to their equivalents in the target language
• Library Equivalents: Identifies equivalent libraries and frameworks in the target language ecosystem
• Type System Adaptation: Handles differences in type systems (static vs. dynamic, nullable vs. non-nullable, generics, type inference)
• Idiom Translation: Converts source-language idioms to target-language idioms rather than producing literal (non-idiomatic) translations
• Error Handling Translation: Maps exception handling, error return patterns, and result types between languages
• Testing the Translation: Verifies that the translated code produces identical outputs for the same inputs

Instructions

Step 1: Analyze the Source Code

Before translating, understand the source code fully.

Analysis Checklist

1. Identify all language-specific constructs: list comprehensions, pattern matching, operator overloading, extension methods, macros, decorators, annotations
2. Catalog external dependencies: libraries, frameworks, system APIs used by the source code
3. Map data structures: identify which data structures are used and their properties (ordered, mutable, nullable)
4. Understand error handling: exceptions, error codes, Result/Option types, panic/recover
5. Note concurrency patterns: threads, async/await, goroutines, actors, coroutines
6. Check for language-specific behavior: integer overflow, floating-point precision, string encoding, null semantics

Step 2: Map Language Constructs

Use the following reference tables to map constructs between common language pairs.

Core Construct Mapping

Collection Operation Mapping

Step 3: Translate with Idiomatic Style

Produce code that reads naturally in the target language, not a literal word-for-word translation.

Example: Python to JavaScript Translation

Python source:

from dataclasses import dataclass, field
from typing import List, Optional
from datetime import datetime


@dataclass
class Task:
    id: str
    title: str
    description: str = ""
    completed: bool = False
    tags: List[str] = field(default_factory=list)
    due_date: Optional[datetime] = None
    created_at: datetime = field(default_factory=datetime.now)

    def is_overdue(self) -> bool:
        if self.due_date is None or self.completed:
            return False
        return datetime.now() > self.due_date

    def add_tag(self, tag: str) -> None:
        normalized = tag.strip().lower()
        if normalized and normalized not in self.tags:
            self.tags.append(normalized)


class TaskManager:
    def __init__(self):
        self._tasks: dict[str, Task] = {}

    def add_task(self, task: Task) -> None:
        if task.id in self._tasks:
            raise ValueError(f"Task with id '{task.id}' already exists")
        self._tasks[task.id] = task

    def get_overdue_tasks(self) -> List[Task]:
        return [t for t in self._tasks.values() if t.is_overdue()]

    def get_tasks_by_tag(self, tag: str) -> List[Task]:
        normalized = tag.strip().lower()
        return [t for t in self._tasks.values() if normalized in t.tags]

    def complete_task(self, task_id: str) -> Task:
        task = self._tasks.get(task_id)
        if task is None:
            raise KeyError(f"Task '{task_id}' not found")
        task.completed = True
        return task

    def get_summary(self) -> dict:
        total = len(self._tasks)
        completed = sum(1 for t in self._tasks.values() if t.completed)
        overdue = len(self.get_overdue_tasks())
        return {
            "total": total,
            "completed": completed,
            "pending": total - completed,
            "overdue": overdue,
        }

JavaScript translation (idiomatic):

class Task {
    constructor(id, title, { description = "", completed = false, tags = [], dueDate = null } = {}) {
        this.id = id;
        this.title = title;
        this.description = description;
        this.completed = completed;
        this.tags = [...tags];
        this.dueDate = dueDate;
        this.createdAt = new Date();
    }

    isOverdue() {
        if (!this.dueDate || this.completed) return false;
        return new Date() > this.dueDate;
    }

    addTag(tag) {
        const normalized = tag.trim().toLowerCase();
        if (normalized && !this.tags.includes(normalized)) {
            this.tags.push(normalized);
        }
    }
}

class TaskManager {
    #tasks = new Map();

    addTask(task) {
        if (this.#tasks.has(task.id)) {
            throw new Error(`Task with id '${task.id}' already exists`);
        }
        this.#tasks.set(task.id, task);
    }

    getOverdueTasks() {
        return [...this.#tasks.values()].filter(t => t.isOverdue());
    }

    getTasksByTag(tag) {
        const normalized = tag.trim().toLowerCase();
        return [...this.#tasks.values()].filter(t => t.tags.includes(normalized));
    }

    completeTask(taskId) {
        const task = this.#tasks.get(taskId);
        if (!task) {
            throw new Error(`Task '${taskId}' not found`);
        }
        task.completed = true;
        return task;
    }

    getSummary() {
        const tasks = [...this.#tasks.values()];
        const total = tasks.length;
        const completed = tasks.filter(t => t.completed).length;
        const overdue = this.getOverdueTasks().length;
        return { total, completed, pending: total - completed, overdue };
    }
}

Translation notes:

Example: JavaScript to Java Translation

JavaScript source:

async function fetchUserProfile(userId) {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) {
        throw new Error(`Failed to fetch user: ${response.status}`);
    }
    const data = await response.json();
    return {
        id: data.id,
        name: `${data.firstName} ${data.lastName}`,
        email: data.email,
        isActive: data.status === "active",
        roles: data.roles?.map(r => r.name) ?? [],
    };
}

Java translation (idiomatic):

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Collections;
import java.util.List;
import java.util.Optional;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public record UserProfile(
    String id,
    String name,
    String email,
    boolean isActive,
    List<String> roles
) {}

public class UserProfileService {
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private final String baseUrl;

    public UserProfileService(HttpClient httpClient, ObjectMapper objectMapper, String baseUrl) {
        this.httpClient = httpClient;
        this.objectMapper = objectMapper;
        this.baseUrl = baseUrl;
    }

    public UserProfile fetchUserProfile(String userId) throws UserFetchException {
        try {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/api/users/" + userId))
                .GET()
                .build();

            HttpResponse<String> response = httpClient.send(
                request, HttpResponse.BodyHandlers.ofString()
            );

            if (response.statusCode() != 200) {
                throw new UserFetchException(
                    "Failed to fetch user: HTTP " + response.statusCode()
                );
            }

            JsonNode data = objectMapper.readTree(response.body());
            String name = data.get("firstName").asText() + " " + data.get("lastName").asText();
            boolean isActive = "active".equals(data.path("status").asText());

            List<String> roles = Optional.ofNullable(data.get("roles"))
                .filter(JsonNode::isArray)
                .map(rolesNode -> {
                    List<String> result = new java.util.ArrayList<>();
                    rolesNode.forEach(r -> result.add(r.get("name").asText()));
                    return Collections.unmodifiableList(result);
                })
                .orElse(Collections.emptyList());

            return new UserProfile(
                data.get("id").asText(),
                name,
                data.get("email").asText(),
                isActive,
                roles
            );
        } catch (UserFetchException e) {
            throw e;
        } catch (Exception e) {
            throw new UserFetchException("Error fetching user profile", e);
        }
    }
}

Step 4: Map Library Equivalents

When the source code uses language-specific libraries, find the equivalent in the target language.

Common Library Equivalents

Step 5: Handle Type System Differences

Different type systems require careful adaptation during translation.

Step 6: Test the Translation

Verify that the translated code produces identical results to the source code.

Testing Strategy

1. Port the test suite: translate unit tests alongside the production code; if tests pass in both languages, the translation is likely correct
2. Use golden output comparison: run both implementations with the same inputs and compare outputs character by character
3. Test edge cases: null/undefined, empty collections, boundary values, special characters, and error conditions
4. Test error behavior: verify that both versions throw errors for the same invalid inputs

Python Example: Translation Verification Test

import subprocess
import json


def test_translation_equivalence():
    """Run both Python and JavaScript implementations with same inputs
    and verify identical outputs."""
    test_cases = [
        {"input": [3, 1, 4, 1, 5], "operation": "sort"},
        {"input": [1, 2, 3, 4, 5], "operation": "filter_even"},
        {"input": [], "operation": "sort"},
        {"input": [None, 1, None, 2], "operation": "remove_nulls"},
    ]

    for case in test_cases:
        input_json = json.dumps(case)

        # Run Python version
        py_result = subprocess.run(
            ["python", "solution.py", input_json],
            capture_output=True, text=True
        )

        # Run JavaScript version
        js_result = subprocess.run(
            ["node", "solution.js", input_json],
            capture_output=True, text=True
        )

        assert py_result.stdout.strip() == js_result.stdout.strip(), (
            f"Mismatch for input {case}: "
            f"Python={py_result.stdout.strip()}, "
            f"JS={js_result.stdout.strip()}"
        )

Best Practices

• Translate idioms, not syntax: a list comprehension in Python should become .filter().map() in JavaScript, not a for loop that builds an array; each language has its own natural way of expressing the same logic
• Preserve the public API contract: method names, parameter order, return types, and error types should match as closely as possible between versions to maintain interoperability expectations
• Translate tests alongside code: tests serve as the specification; translating them ensures the target implementation matches the source behavior
• Use the target language's standard library: do not import a third-party library to replicate a source-language built-in when the target language has an equivalent in its standard library
• Handle encoding and locale differences: string handling, date formatting, and number formatting vary between languages and platforms; explicitly set locale and encoding rather than relying on defaults
• Preserve error semantics: if the source throws a specific exception type, the target should throw an equivalent; do not silently swallow errors or change error types during translation
• Document translation decisions: when a construct has no direct equivalent and a judgment call was made, document the decision and rationale in a comment
• Benchmark performance-critical translations: algorithmic complexity should be preserved, but constant factors and memory usage may differ; benchmark if performance matters

Common Pitfalls

• Literal translation that ignores idioms: writing Java-style code in Python (e.g., getter/setter methods instead of properties, StringBuilder instead of f-strings) produces correct but unidiomatic code that is harder for native developers to maintain
• Missing null/undefined handling differences: Python's None, JavaScript's null and undefined, Java's null, and Rust's Option have different semantics; a direct mapping may introduce bugs at boundaries
• Integer overflow differences: Python integers have arbitrary precision; JavaScript numbers are 64-bit floats; Java integers are fixed-width with overflow; Go integers are fixed-width with silent overflow; Rust integers panic on overflow in debug mode
• String encoding differences: Python 3 strings are Unicode; Java strings are UTF-16; Go strings are UTF-8 byte sequences; JavaScript strings are UTF-16; character indexing and length calculations may differ for non-ASCII text
• Collection mutability differences: Python lists are mutable; Java List.of() returns an immutable list; JavaScript arrays are always mutable; Go slices have copy-on-write gotchas; ensure mutability semantics match
• Concurrency model differences: translating async/await from JavaScript to Java requires understanding that JavaScript is single-threaded while Java is multi-threaded; thread safety concerns that do not exist in JavaScript may exist in Java
• Equality semantics: Python's == compares values; JavaScript's === compares values and types; Java's == compares references (for objects); ensure equality checks are translated correctly
• Default parameter handling: Python evaluates default parameters once at function definition time (mutable default pitfall); JavaScript evaluates defaults at each call; Java does not support default parameters; each requires different translation patterns
• Error handling model mismatch: translating Python exceptions to Go error returns (or Rust Results) requires restructuring control flow, not just swapping syntax