AI-Powered Code Migration Between Programming Languages
Migrating a codebase from one language to another has traditionally been solved in two ways: rewrite manually (expensive and time-consuming) or find transpilers (narrow applicability, low quality output). AI migration occupies a middle ground: it doesn't just translate syntax, but adapts idioms, replaces libraries with idiomatic equivalents, and accounts for target language characteristics.
Migration System Architecture
Naive approach — feed the entire file to an LLM and ask to translate. It works for files up to 200-300 lines. Real codebases need a different architecture:
Dependency Analyzer — builds a dependency graph between files/modules. Determines migration order.
Chunk Splitter — divides files into independent chunks (class, function, module) that can be migrated and tested separately.
Context Manager — passes already-migrated dependencies to the LLM so new files use correct imports.
Validator — compiles and tests migrated code.
Glossary — dictionary of correspondences: original library → target language library.
Python → TypeScript Migration
from anthropic import Anthropic
from pathlib import Path
import ast
import json
from typing import Optional
client = Anthropic()
# Glossary mapping Python → TypeScript/Node.js
PYTHON_TO_TS_GLOSSARY = {
"fastapi": "express + zod (or hono)",
"pydantic": "zod",
"sqlalchemy": "prisma (or drizzle-orm)",
"pytest": "jest (or vitest)",
"requests": "fetch (native) or axios",
"asyncio": "native async/await + Promise",
"datetime": "Date + date-fns",
"pathlib": "path (node built-in)",
"dataclass": "interface or class with constructor",
"TypedDict": "interface",
"Optional[X]": "X | undefined",
"List[X]": "X[]",
"Dict[K, V]": "Record<K, V>",
}
MIGRATION_SYSTEM = """You are a senior engineer migrating Python code to TypeScript.
Principles:
- Use TypeScript idioms, not Python with different syntax
- Pydantic models → Zod schemas + TypeScript interfaces
- SQLAlchemy → Prisma (if ORM) or raw SQL with types
- FastAPI decorators → Express/Hono routes
- Python async/await → TypeScript async/await (identical semantics)
- Exception handling: Python exceptions → TypeScript Error classes + Result types
- Type hints → strict TypeScript types (no any)
TypeScript file structure:
1. imports (use ESM)
2. types/interfaces
3. constants
4. main code
Conventions:
- snake_case → camelCase for variables/functions
- snake_case → PascalCase for classes
- Add JSDoc for public functions"""
class PythonToTypeScriptMigrator:
def __init__(self):
self.migrated_modules: dict[str, str] = {} # original_path -> ts_content
self.type_glossary: dict[str, str] = {} # python_type -> ts_type
def migrate_file(
self,
py_file: str,
related_migrations: Optional[dict[str, str]] = None,
) -> str:
"""Migrates one Python file to TypeScript"""
source = Path(py_file).read_text()
# Parse imports via AST
imports = self._extract_imports(source)
library_mapping = self._map_libraries(imports)
# Gather context from already-migrated dependencies
context_parts = []
if related_migrations:
for dep_file, ts_content in related_migrations.items():
context_parts.append(
f"// Already migrated: {dep_file}\n{ts_content[:1000]}"
)
context = "\n\n".join(context_parts) if context_parts else ""
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=8096,
system=MIGRATION_SYSTEM,
messages=[{
"role": "user",
"content": f"""Migrate Python file to TypeScript.
File: {py_file}
```python
{source}
Libraries (Python → TypeScript): {json.dumps(library_mapping, ensure_ascii=False, indent=2)}
{f"Context of already-migrated dependencies:{chr(10)}{context}" if context else ""}
Return only the TypeScript file code.""" }] )
ts_code = response.content[0].text
# Remove markdown wrapper if present
if "```typescript" in ts_code:
ts_code = ts_code.split("```typescript")[1].split("```")[0].strip()
elif "```" in ts_code:
ts_code = ts_code.split("```")[1].split("```")[0].strip()
return ts_code
def _extract_imports(self, source: str) -> list[str]:
"""Extract imports via AST"""
try:
tree = ast.parse(source)
imports = []
for node in ast.walk(tree):
if isinstance(node, ast.Import):
imports.extend(alias.name for alias in node.names)
elif isinstance(node, ast.ImportFrom):
if node.module:
imports.append(node.module.split(".")[0])
return list(set(imports))
except SyntaxError:
return []
def _map_libraries(self, python_imports: list[str]) -> dict:
"""Maps Python libraries to TypeScript equivalents"""
mapping = {}
for lib in python_imports:
if lib in PYTHON_TO_TS_GLOSSARY:
mapping[lib] = PYTHON_TO_TS_GLOSSARY[lib]
return mapping
def migrate_project(self, src_dir: str, output_dir: str) -> dict:
"""Migrates entire Python project to TypeScript"""
src_path = Path(src_dir)
output_path = Path(output_dir)
output_path.mkdir(parents=True, exist_ok=True)
# Build dependency graph
files = list(src_path.rglob("*.py"))
migration_order = self._topological_sort(files)
results = {}
for py_file in migration_order:
if py_file.name.startswith("test_"):
continue # Tests migrated separately
# Get already-migrated dependencies
related = {
str(dep): self.migrated_modules[str(dep)]
for dep in migration_order
if str(dep) in self.migrated_modules
}
ts_content = self.migrate_file(str(py_file), related[-3:] if len(related) > 3 else related)
# Save
relative = py_file.relative_to(src_path)
ts_file = output_path / relative.with_suffix(".ts")
ts_file.parent.mkdir(parents=True, exist_ok=True)
ts_file.write_text(ts_content)
self.migrated_modules[str(py_file)] = ts_content
results[str(py_file)] = str(ts_file)
return results
def _topological_sort(self, files: list[Path]) -> list[Path]:
"""Sorts files in dependency order (simplified version)"""
# Simple heuristic: first models, then utilities, then services, then routes
priority = {"model": 0, "schema": 0, "type": 0, "util": 1, "helper": 1,
"service": 2, "repo": 2, "route": 3, "handler": 3, "view": 3, "app": 4}
def get_priority(path: Path) -> int:
name = path.stem.lower()
for key, p in priority.items():
if key in name:
return p
return 2 # Default
return sorted(files, key=get_priority)
### Migration with Validation
```python
def migrate_and_validate(py_file: str, ts_output: str) -> dict:
"""Migrates file and runs TypeScript compiler"""
import subprocess
migrator = PythonToTypeScriptMigrator()
ts_code = migrator.migrate_file(py_file)
Path(ts_output).write_text(ts_code)
# Compile to check types
result = subprocess.run(
["npx", "tsc", "--noEmit", "--strict", ts_output],
capture_output=True, text=True
)
if result.returncode != 0:
# Try to fix compilation errors
fixed_code = fix_typescript_errors(ts_code, result.stdout + result.stderr)
Path(ts_output).write_text(fixed_code)
result = subprocess.run(
["npx", "tsc", "--noEmit", "--strict", ts_output],
capture_output=True, text=True
)
return {
"success": result.returncode == 0,
"errors": result.stdout + result.stderr if result.returncode != 0 else "",
"output_file": ts_output,
}
def fix_typescript_errors(ts_code: str, errors: str) -> str:
"""Fixes TypeScript compiler errors via LLM"""
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=8096,
messages=[{
"role": "user",
"content": f"""Fix TypeScript compiler errors.
Code:
```typescript
{ts_code}
Compiler errors:
{errors}
Return fixed code."""
}]
)
text = response.content[0].text
if "typescript" in text: return text.split("typescript")[1].split("```")[0].strip()
return text
### Other Migration Directions
The system works similarly for other language pairs. Key differences are in library glossaries:
**Java → Kotlin**: jackson → kotlinx.serialization, Spring annotations → Ktor/Spring equivalents, checked exceptions → sealed classes with Result.
**PHP → Python**: Laravel Eloquent → SQLAlchemy, Blade templates → Jinja2, Composer → pip/uv.
**JavaScript → TypeScript**: main work — adding types, replacing `any` with concrete types, adding Zod validation at boundaries.
### Practical Case: Python Microservice → TypeScript
**Context**: startup migrated notification service (Python FastAPI, 3,200 lines) to TypeScript for stack unification (frontend team only knew JS/TS).
**Scope**: 28 files, 12 Pydantic models, 34 API endpoints, 180 unit tests.
**Process (2 weeks)**:
- Week 1: glossary setup, model and utility migration (automatic), manual refinement of 3 complex files with business logic
- Week 2: route migration, test adaptation (Jest), integration testing
**Results**:
- 85% of code migrated automatically without manual fixes
- 15% required refinement (complex logic with Python-specific idioms)
- TypeScript compilation errors: 47 → 0 (after 2 iterations of LLM fix)
- Test coverage of migrated service: 71% (was 74% in Python — minimal loss)
**Unexpected bonus**: during migration, AI identified 3 places with potential race conditions in Python code, which were fixed in the TypeScript version.
### Timeline
- Prototype migration of one file: 1–2 days
- System with dependency graph and batch-migration: 1 week
- Validation + auto-fix loop: 1 week
- Full project migration 5,000–15,000 lines: 3–6 weeks (including QA)