code-translator

Translate source code with Gemma, then review and fix it with Claude or Codex — usable as a library, a CLI, or an MCP server.

The pipeline has three stages:

1. Translate — google-genai with Gemma (default gemma-4-26b-a4b-it, any model overridable).
2. Validate — per-language compiler/AST + linter plugins (run whatever toolchains are installed).
3. Review/fix — your choice of claude (Claude Agent SDK, claude-opus-4-8, effort max) or codex (the codex CLI, latest model, reasoning effort high), looping until the validators pass.

Setup

pip install -e .          # installs the `code-translator` and `code-translator-mcp` scripts

pip install -e . is what registers the code-translator and code-translator-mcp console scripts. Until you install, you can run the tool directly without installing:

python code-translator.py ...          # same as the `code-translator` script
python -m code_translator ...          # equivalent
python -m code_translator.mcp_server   # same as `code-translator-mcp`

Credentials:

• Gemma/translation needs GEMINI_API_KEY in the environment or a .env file (searched in ./.env, ./src/.env, and the repo root).
• Claude review uses the logged-in claude CLI (claude login); no API key in the repo.
• Codex review uses the logged-in codex CLI (codex login).

Run code-translator doctor to see which reviewers and language toolchains are available.

CLI

# Translate only (Gemma)
code-translator translate src/balloon.c zig -o balloon.zig

# Full pipeline: translate -> validate -> review/fix -> deliver
code-translator run src/balloon.c zig --reviewer claude -o balloon.zig
code-translator run src/balloon.c c   --reviewer codex  -o balloon_out.c

# Review/fix an existing translation
code-translator review balloon.zig -l zig --reviewer claude -s src/balloon.c

# Environment report
code-translator doctor

--reviewer is required for review/run — you choose the provider, every time.

MCP (for agents)

The MCP server exposes the same pipeline as tools any MCP-capable agent can call. It speaks stdio and is named code-translator.

code-translator-mcp            # stdio server; or: python -m code_translator.mcp_server

Long-running tools. review_code and translate_and_review_code drive Claude/Codex at max effort, looping up to max_iterations times, so a single call can run for several minutes. The server streams every stage as an MCP progress + log notification, which resets the client's per-call timeout and shows live progress — so the default ~120s ceiling no longer trips them. For very large jobs you can still raise the client's tool timeout (in Claude Code, MCP_TOOL_TIMEOUT), or lower max_iterations.

Registering the server

Claude Code (one-liner):

claude mcp add code-translator -- code-translator-mcp
# not installed? point it at the module via your venv python:
claude mcp add code-translator -- /path/to/.venv/bin/python -m code_translator.mcp_server

Claude Desktop / generic MCP client (mcpServers config). Use the installed script…

{
  "mcpServers": {
    "code-translator": {
      "command": "code-translator-mcp",
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

…or, without installing, run the module directly (set cwd to the repo so .env is found):

{
  "mcpServers": {
    "code-translator": {
      "command": "python",
      "args": ["-m", "code_translator.mcp_server"],
      "cwd": "C:/Users/Rudy/Desktop/Projects/code-translator",
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

The Claude/Codex reviewers authenticate through their own logged-in CLIs (claude login, codex login) on the host running the server — no keys go in the MCP config. Only GEMINI_API_KEY (for translation) is needed there, and only if it isn't already in a .env.

Tools

Tool	Required args	Optional args	Returns
translate_code	source_code, target_language	source_language, source_path, model (default gemma-4-26b-a4b-it)	{ code, model, target_language, log }
review_code	code, target_language, reviewer	source_code, model, max_iterations (3)	{ code, reviewer, model, iterations, fixed, validation_ok, remaining[], log }
translate_and_review_code	source_code, target_language, reviewer	source_language, source_path, translate_model, review_model, max_iterations (3)	{ code, translation_model, reviewer, review_model, iterations, fixed, validation_ok, remaining[], log }
list_supported_languages	—	—	{ languages: [ { language, validators: [ { validator, tool, available } ] } ] }
list_reviewers	—	—	{ reviewers: [ { name, default_model, available } ] }

• reviewer is required for any review and must be "claude" or "codex" — the agent chooses, there is no default. Call list_reviewers first to see which are available.
• target_language accepts canonical names or common aliases: python/py, c, cpp/c++, zig, go/golang, rust/rs, javascript/js, typescript/ts, java.
• Each remaining[] item is { message, severity, line, column, tool } — these are compiler/AST errors the reviewer could not resolve within max_iterations.

How an agent should use it

1. (Optional) Call list_reviewers / list_supported_languages to confirm what's available.
2. For a one-shot translation with review, call translate_and_review_code with source_code, target_language, and reviewer. For an existing translation you want checked/fixed, call review_code and pass the original as source_code for context.
3. Inspect validation_ok:
   • true → the delivered code passes every installed validator (or only validators whose toolchain is missing were skipped). Use it.
   • false → read remaining[]. Retry with a higher max_iterations, switch reviewer, or surface the diagnostics to the user.
4. fixed says whether the reviewer changed anything; iterations is how many passes ran; log is a human-readable stage list you can stream to the user as progress.

Example call:

{
  "name": "translate_and_review_code",
  "arguments": {
    "source_code": "int add(int a, int b) { return a + b; }",
    "target_language": "zig",
    "reviewer": "claude"
  }
}

Library

from code_translator import translate, review, translate_and_review

result = translate_and_review(open("src/balloon.c").read(), "zig", reviewer="claude",
                              source_path="src/balloon.c")
print(result.code)

Validators & languages

Validators are defined for python, c, c++, zig, go, rust, javascript, typescript, and java. Each uses that language's real tooling (e.g. clang -fsyntax-only, zig ast-check, rustc --emit=metadata, node --check, Python's built-in compiler). A missing toolchain is skipped with a warning, never a hard failure — install the compiler to turn that language's checks on with no code change.