simopich/unbound-translator

Unbound Translator is a set of Python scripts that translate the fan-made Game Boy Advance game Pokemon Unbound into other languages. The project extracts all in-game text from the ROM file, prepares it for translation, runs it through an AI language model, and then writes the translated text back into the ROM. The result is a playable ROM with all dialogue, menus, item descriptions, mission text, and other strings in the target language. The core technical challenge is that Pokemon Unbound is already a 32-megabyte ROM, which is the maximum size for the GBA format. Older translation tools work by expanding the ROM to make room for longer translated text, but that approach does not work here because there is no room to expand into. The project solves this with a hybrid strategy: short translations that still fit in their original locations are written in place, while longer translations are relocated into unused space that already exists inside the ROM. The scripts find this unused space by scanning for long runs of empty bytes. About 1.1 megabytes of such space exists in Unbound, which is enough to hold the relocated text. The workflow runs in numbered steps. Step one extracts all text from the ROM into a JSON file. Step two prepares that text for translation by replacing special game engine control codes with readable placeholder labels so the AI model does not accidentally alter them. Step three sends the text to any OpenAI-compatible chat API, translating in batches with parallel workers and resuming automatically if the process is interrupted. Step four injects the finished translation back into the ROM, handling the in-place and relocation cases separately. The translation step works with any model accessible via an OpenAI-compatible API. You supply the API base URL, key, and model name. The scripts validate that every placeholder and control code is preserved correctly in the returned translations, and retry batches that fail validation before moving on. A separate font injection tool handles characters not present in the GBA's default character set. The project is focused on Italian as its first target translation but is built to support any language. The README includes detailed notes on edge cases: mission title length limits, certain strings that must not be relocated because moving them freezes game routines, and how to audit menu text coverage during extraction.