binbingwu/Multi-Agent-Game-Localizer

English · 简体中文

Claude does the thinking, local models do the heavy lifting.
Claude understands the game, sets the strategy, writes engine plugins and reviews quality;
a local LLM translates tens of thousands of lines in parallel, into any language it knows.
The patch is built on your own PC from your own game files, so there is no need to download a patch from an unknown source.

Why · Architecture · Languages · Requirements · Quick start · Prompting · New engines

AliceSoft's Evenicle (Steam English release, v1.04) translated into Simplified Chinese on an RTX 4070 12GB:

The translated text renders in-game, long lines wrap correctly, and the name box, inner-monologue brackets and multi-line layout match the original release.

flowchart LR
    A[🎮 Game resources] -->|Extraction| B[(state.db<br/>all lines)]
    B -->|Context| C[Glossary<br/>speakers<br/>scene summaries]
    B --> D{Translation<br/>×8 parallel}
    C --> D
    D --> E{QA}
    E -->|✅ pass| F[Package]
    E -->|❌ fail<br/>with reason| D
    E -->|failed repeatedly| G[Human review<br/>Claude or you]
    G --> F
    F -->|Build & Validation| H[🌐 Localization patch]

sequenceDiagram
    autonumber
    actor U as You
    participant C as Claude (Orchestrator)
    participant H as Localizer CLI
    participant L as Local LLM (Qwen)
    U->>C: Game folder, version, target language, requirements
    C->>H: init: detect engine, back up originals
    Note over C,H: For an unsupported engine, Claude writes a plugin first
    C->>H: run --limit 5: trial batches
    H->>L: Glossary / summaries / translation requests
    L-->>H: Translations
    H-->>C: Translations + QA results
    C->>C: Compare with the source, adjust strategy, glossary, rules
    C->>H: run: full translation in the background
    H->>L: Thousands of batches, 8 in parallel
    C->>H: build --install, test screenshot
    C-->>U: Results, screenshots, known issues

Source and target language are set per project. You can use a code or a name:

venv\Scripts\python -m hanhua init MyGame "D:\Games\MyGame" "My Game" --src ja --tgt en
venv\Scripts\python -m hanhua init MyGame "D:\Games\MyGame" "My Game" --src en --tgt "Brazilian Portuguese"

A profile defines punctuation rules, a plausible length ratio for QA, and whether leftover source-language words should be flagged. Run python -m hanhua langs to list them, or add your own in hanhua/langs.py.

1. Install

git clone https://github.com/binbingwu/Multi-Agent-Game-Localizer.git
cd Multi-Agent-Game-Localizer
python -m venv venv
venv\Scripts\pip install pillow
venv\Scripts\python -m hanhua setup

2. Hand it to Claude

Open Claude Code in this folder and send it the prompt from the next section.

3. Or run it yourself

For engines that are already supported you can skip Claude and use the commands below, or double-click 汉化器.bat for a menu. The menu and log messages are in Chinese.

venv\Scripts\python -m hanhua init <project> "<game dir>" "<title>" --src en --tgt ja   :: create project, back up originals
venv\Scripts\python -m hanhua run <project> --limit 5          :: trial: 5 batches only
venv\Scripts\python -m hanhua run <project>                    :: full pipeline, resumable
venv\Scripts\python -m hanhua status <project>                 :: progress
venv\Scripts\python -m hanhua build <project> --install        :: package and install (close the game first)
venv\Scripts\python -m hanhua test <project>                   :: launch the game, screenshot, close
venv\Scripts\python -m hanhua export <project>                 :: export lines needing review to review.tsv
venv\Scripts\python -m hanhua import <project> review.tsv      :: import your fixes (locked)
venv\Scripts\python -m hanhua uninstall <project>              :: restore the original files
venv\Scripts\python -m hanhua langs                            :: list language profiles

When Claude opens this folder it reads CLAUDE.md, which describes its role as orchestrator, the workflow and the rules. You only need to say where the game is, what you want, and what must not be touched.

You are the orchestrator of this localizer; follow CLAUDE.md.
Game: <name>, folder D:\Games\XXX, Steam English release v1.2 (originally Japanese, I only own the English version).
Translate into: German. Text only (no images or voice). Adult content translated faithfully.
Detect the engine, translate a small trial batch and show me the quality before running everything.
My PC has an RTX 4070 12GB. The game may be open: make sure it is closed before installing, and don't touch my saves.

Show me 30 freshly translated lines next to the source and point out the weak ones.
Change these names: X → A, Y → B, and send the affected lines back for retranslation.
What is the most common QA failure? Is it the model or are the rules too strict?
Build, install, launch the game and show me a screenshot to check wrapping and the font.

Each game gets projects/<project>/:

Line status: new → translated → qa_ok. Failures become qa_fail and go back with the reason. After too many retries they become review; they are still packaged, but you should export and fix them. Locked lines are never overwritten by the model.

Implement the interface in base.py in hanhua/engines/<engine>/plugin.py and register it in hanhua/engines/__init__.py:

Context, translation, QA and packaging need no changes. The easiest way is to tell Claude:

This game uses the XX engine. Write a plugin for it modelled on the System 4 plugin,
and verify in-game with a few translated lines that the text displays.

汉化器.bat              menu launcher (Chinese UI)
config.json            model, parallel slots, batch size, default languages, QA thresholds
CLAUDE.md              instructions for Claude as orchestrator
docs/                  README images
hanhua/
├─ orchestrator.py     pipeline scheduling, translation strategy
├─ langs.py            language profiles
├─ llm.py              local model server (llama.cpp, OpenAI-compatible API)
├─ agents/             extraction · context · translation · qa · build
├─ engines/            engine plugins (system4 implemented)
└─ setup.py            downloads the inference engine, model and tools
tools/gui.ps1          screenshots and simulated clicks for smoke tests

The code is released under GPL-3.0. Parsing of the System 4 font format follows libsys4 / xsystem4 (GPL-2.0+). The unpacking tool alice-tools is GPL.