dazed/DazedTL
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
DazedTL/README.md
DazedAnon 3de5368817 Stabilize injects
2026-07-08 18:11:04 -05:00

26 KiB
Raw Blame History

DazedMTLTool

An AI-powered game translation tool with a GUI. Translate RPG Maker, Ren'Py, Tyrano, Wolf RPG, Kirikiri, and other game engines from Japanese to English using GPT, Gemini, Mistral, or other compatible AI models.

Credits

  • Sinflower — RV2JSON — enables RPGMaker Ace games to be translated the same way as MV/MZ by converting rvdata2 files to JSON and back. A curated copy is bundled offline in util/ace/offline/ and updates with DazedMTLTool.
  • Sakura & Kao_SSS — TL Inspector (util/tl_inspector/) — in-game translation source inspector and live-edit plugin for RPG Maker MV/MZ playtesting.
  • Len — Forge MV/MZ playtest plugin (util/forge/), Mistral API support (provider integration and adaptive rate limiting), and batch translation mode (Anthropic Message Batches API).

Table of Contents

Supported Engines

  • RPG Maker (MV, MZ, Ace, and more)
  • Wolf RPG Editor
  • Ren'Py
  • TyranoBuilder / TyranoScript
  • Kirikiri
  • NScripter
  • CSV / Text files

Requirements

  • Python 3.12 – 3.14 — See Installing Python below if you don't have it yet.
  • An AI API Key — You'll need an API key from OpenAI, Google Gemini, Mistral (free tier available — no credit card), or a compatible provider.

Installing Python

If you already have Python 3.12–3.14 installed and working, skip to Quick Start.

Step 1 — Download

Go to python.org/downloads and download Python 3.13 (or any version from 3.12 to 3.14).

Step 2 — Install (Important!)

When the installer opens, check both boxes at the bottom before clicking Install:

  • ✅ "Add python.exe to PATH" — This is the most important step. Without it, your system won't be able to find Python.
  • ✅ "Use admin privileges when installing pip"

Then click Install Now. The default settings are fine for everything else.

Step 3 — Verify

Open a new terminal window (don't reuse an old one — it won't see the new PATH) and run:

python -V

You should see something like Python 3.13.x. Then check pip:

pip -V

You should see something like pip 24.x.x from ....

If python or pip is not recognized

This means Python wasn't added to your PATH. You have two options:

Option A — Reinstall (easiest)

  1. Open the Python installer again (or redownload it).
  2. Select Modify.
  3. Click Next on the first screen.
  4. On the Advanced Options screen, check "Add Python to environment variables".
  5. Click Install. Then open a new terminal and try again.

Option B — Add to PATH manually

  1. Press Win+R, type sysdm.cpl, press Enter.
  2. Go to the Advanced tab → Environment Variables.
  3. Under System variables, find Path and click Edit.
  4. Click New and add the path where Python was installed. Typically:
    • C:\Users\YourName\AppData\Local\Programs\Python\Python313\
    • C:\Users\YourName\AppData\Local\Programs\Python\Python313\Scripts\
  5. Click OK on all dialogs, then open a new terminal and try python -V again.

Tip: If python works but pip doesn't, try python -m pip -V instead. If that works, you can use python -m pip install anywhere you'd normally use pip install.

Quick Start

1. Download the Tool

  1. Click the green Code button at the top of this page and select Download ZIP.
  2. Extract the ZIP to a folder of your choice (e.g., C:\DazedMTLTool).

2. Set Up Your API Key

  1. Inside the tool folder, find .env.example and make a copy of it named .env.
  2. Open .env in any text editor (Notepad works fine) and fill in your API details:
    • api — Your API base URL (for Nvidia use https://integrate.api.nvidia.com/v1/, for Mistral use https://api.mistral.ai/v1/).
    • key — Your API key.
    • organization — Your organization key (make something up if using a self-hosted or non-OpenAI API).
    • API_PROVIDER — Use openai for OpenAI-compatible providers (including Nvidia), gemini for Gemini, or mistral for Mistral (only needed when api is left empty).
    • model — For Nvidia/custom OpenAI-compatible endpoints, enter the model name manually (example: deepseek-ai/deepseek-v4-pro).
  3. The rest of the settings (wordwrap, batch size, etc.) can be left as defaults for now. You can tweak them later.

Trying Mistral? Set API_PROVIDER=mistral, add your key, use mistral-medium-3.5. Free tier details in Mistral API (free tier).

3. Launch the GUI

Windows: Double-click START.bat. It will create a virtual environment, install dependencies, and open the GUI.

Linux/macOS: Run ./START.sh, or double-click DazedMTLTool.desktop (choose Allow Launching when your file manager asks). From then on, either method works.

That's it! Use the same launcher each time you want to open the tool.

Using the GUI

The GUI has several tabs that handle different parts of the translation process:

Config Tab

This is where you configure your API settings, wordwrap widths, and other options. Most of these mirror what's in the .env file, but you can adjust them visually.

Translation Tab

The main tab for translating files.

  1. Add files — Place the game files you want to translate into the files folder (inside the tool directory).
  2. Select a module — Pick the engine that matches your game (e.g., RPG Maker MV/MZ, Wolf RPG, Ren'Py, etc.).
  3. Click Translate — The tool will process each file and output translated versions to the translated folder.
  4. Copy the results — Move the translated files from translated back into your game's data folder.

Engine Config Tab

Engine-specific settings. RPG Maker has the most mature support — you can toggle exactly which event codes to translate (dialogue, choices, variables, plugin commands, etc.). The defaults cover ~95% of a game's text out of the box. See the RPG Maker Translation Workflow section for a detailed step-by-step guide.

Other engines (Wolf RPG, Ren'Py, Tyrano, etc.) have less granular support and may require more manual tweaking or post-editing depending on the game.

RPG Maker / Wolf / CSV Tabs

Specialized tabs with extra options for those specific engines.

Vocab & Prompt

data/vocab.txt

This file gives the AI context about your game — character names, genders, recurring terms, etc. The better your vocab file, the more consistent the translation.

On first run, data/vocab.txt is created automatically from data/vocab_base.txt if it does not exist yet. Add entries like:

# Game Characters
水無月 士乃 (Minazuki Shino) - Female
暗黒斎 (Dark Kokusai) - Male
フトシ (Futoshi) - Male

Format: Japanese name, English name in parentheses, then gender.

Note: A very large vocab file can increase API costs and potentially reduce quality. Focus on the most important characters and terms.

data/prompt.txt

This is the system prompt sent to the AI. A default data/prompt.txt is included and works well for most games. You generally don't need to edit it unless you want to customize the translation style.

Tips

  • Check log/translations.txt after a run to see what was translated. You can copy useful terms from it into data/vocab.txt for consistency in future runs.
  • Start small — Translate a few files first to make sure the output looks good before doing the whole game.
  • Wordwrap — If text overflows or looks awkward in-game, adjust the width setting in .env or the Config tab. 60 is a good default for most RPG Maker games.
  • Version control — Using Git with the game folder is highly recommended. It lets you track every change the translation makes, compare with original files, and roll back if needed.

Mistral API (free tier)

Mistral's API is free for now (no credit card), and the tool has proper support for it — not just a generic OpenAI-compatible URL. Mistral rate-limits pretty aggressively per model, so there's an adaptive limiter that reads the live headers and paces requests automatically. That lets you crank up fileThreads without the run dying to 429s.

mistral-medium-3.5 is the recommended model for translation. Avoid mistral-medium-latest — it still points at the older 3.1 release.

Quick setup in .env:

API_PROVIDER=mistral
api="https://api.mistral.ai/v1/"
key="your-mistral-api-key"
model="mistral-medium-3.5"

When the API URL points at api.mistral.ai, requests are paced automatically. Mistral enforces a per-minute request limit and a per-minute token limit, both per-model — e.g. mistral-medium allows 25 req/min while ministral-3b allows 750/min. The limiter reads both limits from the live x-ratelimit-* response headers, spaces requests so it never overruns the per-minute budget, and honours Retry-After on 429s. Override the seeds with mistralReqPerSec, mistralTokPerMin, and mistralTokenHeadroom in .env if needed (rarely).

Note: Batch mode (50% off) is Anthropic/Claude only. Mistral runs live translation through the rate limiter above.

Batch Translation (Anthropic, 50% off)

Batch mode — see Credits.

When using a Claude model, the CLI offers a third mode that translates through the Anthropic Message Batches API — every token (input, output, and prompt-cache reads/writes) is billed at 50% of the live price. Batches usually finish within an hour (24h worst case), so use it for large jobs where you don't need results immediately.

python start.py
 -> 3. Batch Translate (Anthropic Batches API, 50% off)

How it works (all engine modules are supported automatically):

  1. Pass 1 (collect) — files are processed normally, but instead of calling the API each request is queued to log/batch_requests.json. Requests are byte-identical to live ones: the static prompt.txt block is cached with a 1h TTL, matched vocab and translation history ride along per request, and structured output enforces the exact line count. Speaker/variable names still translate live during this pass (they get embedded into the dialogue payloads, so both passes must resolve them identically) — they're a tiny share of the volume.
  2. Cost estimate — before anything is submitted you get a cost breakdown (batch + cache / batch worst-case / live price) and a y/n confirmation.
  3. Submit / poll / fetch — the batch is submitted, polled until it ends (batchPollInterval env var controls the interval, default 60s), and the results are saved to log/batch_results.json. Ctrl-C while polling is safe — the batch keeps processing server-side.
  4. Pass 2 (consume) — files are processed again; every payload is filled from the batch results through the normal validation pipeline (line counts, placeholders, content checks). Anything the batch missed or that fails validation falls back to the live API automatically, so the output is always complete.

Context note: in live mode the rolling translation history contains the previous batch's English lines; in batch mode requests are independent, so the history carries the previous batch's source lines instead. The model still sees the surrounding scene, and vocab.txt keeps names and terms consistent — so keep your vocab file in good shape for batch runs.

Cost tracking is exact: per-file and total costs printed after the consume pass use the real billed token counts (cache reads at 0.1x, cache writes at 2x, output at the output rate) with the 50% batch discount applied.

python selftest_batch.py round-trips the whole flow offline (no API key needed) if you want to verify the pipeline after making changes.

Folder Structure

Folder Purpose
files/ Place game files here before translating
translated/ Translated output appears here
log/ Translation logs and cache
modules/ Engine-specific translation scripts
gui/ GUI source code

Finding Untranslated Text (Snipping Tool OCR)

When playtesting a translated game, you'll inevitably find text that was missed or needs fixing. The fastest way to grab Japanese text from the screen and search for it in the game files is with the Windows 11 Snipping Tool — its built-in OCR is far better than most dedicated OCR tools for Japanese text.

How to Use It

  1. Press Win+Shift+S to open the Snipping Tool and take a screenshot of the untranslated text in-game.
  2. The screenshot opens in the Snipping Tool editor. Click the Text Actions button (the icon with lines of text) in the toolbar.
  3. The tool will detect and highlight all text in the image. You can now click and drag to select specific text, or click Copy all text to grab everything.
  4. Paste the copied Japanese text into VSCode's search (Ctrl+Shift+F to search across all files) to find exactly where it lives in the game data.
  5. Fix or re-translate that file as needed.

Why Snipping Tool?

  • Built into Windows 11 — no extra software to install.
  • Excellent Japanese OCR — handles kanji, hiragana, and katakana very accurately, even from stylized game fonts.
  • Quick workflow — screenshot → copy text → paste into search, all in a few seconds.

Tip: If you're on Windows 10 or the Text Actions button doesn't appear, make sure Snipping Tool is updated via the Microsoft Store. Alternatively, ShareX with its OCR feature is a good free option.

RPG Maker Translation Workflow

Here's the recommended step-by-step process for translating an RPG Maker MV/MZ game. This is also shown inside the GUI's RPG Maker tab.

Step Action
1 Parse speakers → vocab — Use the Parse Speakers feature to pull character names from the game files into data/vocab.txt.
2 Identify speaker genders — Figure out which characters are male/female and update data/vocab.txt accordingly. This helps the AI use correct pronouns.
3 Translate Actors.json, MapInfos.json — These are small files with character and map names. Good to do first.
4 Translate Items, System, Weapons, etc. — All the data files that aren't maps or events. Place them in files/, translate, then copy results back.
5 Find speaker names — Enable CODE 101 (Speakers), check for bracketed names, or use the "First Line = Speaker" option to capture speaker names properly.
6 Replace \n[0-999] variables — Some games use variable codes like \n[1] for character names. Replace these with the actual actor names so the AI can translate around them.
7 Translate Maps & CommonEvents — The bulk of the game's dialogue. Start with a small map to test, then do the rest. You can use Estimate in the GUI to check the cost before running.
8 Edit plugins for menus/text — Some UI text lives in plugins.js or plugin parameters. You may need to manually translate these in a text editor.
9 Translate CODE 122 vars, 356 plugins as needed — Enable these codes in the RPG Maker tab if the game stores dialogue in variables or plugin commands.
10 Playtest → find issues → fix → repeat — Play through the game, screenshot any untranslated text, search for it in the game files, and re-translate as needed.

Note: Some text (e.g., CODE 122 variables) may only update when starting a new save file.

Wolf RPG (WolfDawn) Translation Workflow

WOLF RPG Editor games are handled by a dedicated, guided workflow built on the bundled WolfDawn wolf CLI. It unpacks the game's .wolf archives, extracts every translatable string to JSON, translates it with the same AI pipeline used elsewhere, then injects the results back into the game byte-exact.

Open the Workflow tab and choose Wolf RPG (WolfDawn) from the engine selector at the top.

Step Action
0 Project Select the game root folder (browse or Enter — detection also runs when you reopen the tab). If wolf_json/ does not exist yet, the tool automatically unpacks .wolf archives when needed and extracts text into the game's wolf_json/ folder (maps, common events, databases, Game.dat, Evtext, and names.json). A checklist lists every JSON file in wolf_json/; tick the ones you want and click Import (or leave Step 0 — checked files auto-import into the tool's files/ folder, matching the RPG Maker workflow). Extraction snapshots pristine binaries into wolf_json/originals/ for idempotent inject in Step 6.
1 Pre-process Optional: dazedformat normalises JSON in wolf_json/ and files/ (json.dump, indent 4) for clean git diffs; Copy gameupdate/ installs the updater scripts, patch scripts, and .gitignore into the game root for git-based patching. Paths auto-fill from Step 0.
2 Glossary Build vocab.txt before translating: copy the WOLF-tailored prompt into Cursor/Copilot with the extracted files/ JSON, let it discover character names, speech registers, and lore terms, then paste the result into the in-tab editor and save. Item/skill/enemy value names (names.json) are translated in Step 3 and harvested into vocab.txt automatically during Phase 0 — do not list them here.
3 Names Translate names.json (item/skill/enemy/map value names). WolfDawn tags each name with a per-entry safety badge (safe, refs, or verify). Phase 0 translates only safe entries; refs and verify names stay Japanese so inject skips them. Review the category breakdown for this game, pick Translation mode (Normal or Batch), and run Translate safe names (Phase 0).
4 Database Review the discovery summary to see where this game's text lives (standard RPG sheets vs custom dialogue tables). Database sheets are classified as foundation (items, skills, descriptions — translate first) or narrative (custom event/profile sheets — translate after foundation). Use Translate foundation DB then Translate narrative DB, or tick specific sheets and run Translate checked sheets only. Optional: copy the DB structure prompt for an AI audit and import the returned JSON into wolf_json/db_profile.json.
5 Maps/Events Translate map scripts (.mps), common events (CommonEvent.dat), Game.dat, and Evtext. Run after Steps 3–4 so vocab and database terms are consistent. Configure speaker handling for low-confidence nameplate guesses. Batch mode is recommended for large CommonEvent.dat files.
6 Inject Tick translated JSON files from translated/, then Inject selected or Inject all. Each file is reported individually; failures open a dialog with details. Uses pristine originals from wolf_json/originals/.
7 Fix wrap Paste overflowing in-game text to search translated/ JSON and jump to the database sheet and row (sheet names match Step 4 and names.json notes, e.g. ├■街の噂（MOB）). Edit the line, set wrap width, Wrap this row or Wrap all overflowing rows in this sheet, save, then Inject this file (usually DataBase.project.json). Per-sheet widths are remembered in wolf_json/wrap_profile.json. Advanced: wolf relayout for event message boxes (maps/CommonEvent only — not bulletin-style DB UI) and wolf desc-relayout for standard 説明 description fields.
8 Package Run from loose Data/ (backs up Data.wolf → .bak) or repack Data.wolf.
9 Saves (Optional) Update existing .sav files for the translated build.

Recommended order by game layout

After Step 0 extract, the Database tab discovery report classifies your game:

Layout What to do
DB-heavy (most dialogue in custom database sheets) Names → foundation DB → narrative DB → maps/events
Classic RPG (most dialogue in maps/common events) Names → foundation DB → maps/events (skip narrative DB if none)
Hybrid Names → foundation DB → narrative DB → maps/events

wolf binary: Prebuilt wolf CLIs for Windows and Linux are bundled offline under util/wolfdawn/bin/<platform>/, so no toolchain or build step is needed. They update when you update DazedMTLTool. If your platform's binary is missing, update the tool or ask the maintainer to refresh the bundled copy.

Legacy modules: The older Wolf RPG / Wolf RPG 2 modules (configured in the Engine Config tab) still exist for edge cases, but the WolfDawn workflow above is the recommended path.

Using Copilot & VSCode

VSCode is a free code editor, and with GitHub Copilot you get an AI assistant built right into it. This is incredibly useful for translation work — you can ask the AI to help modify game files or even tweak the tool's modules without needing to know how to code.

Setup

  1. Install VSCode.
  2. Install the GitHub Copilot extension (Ctrl+Shift+X → search "GitHub Copilot").
  3. Sign in with your GitHub account (Copilot has a free tier).

Editing Game Files with AI

Open your game folder in VSCode (Right Click → Open with Code) and use Copilot Chat (Ctrl+Shift+I) to ask for changes. Examples:

  • "Replace all \n[1] with Shino in this file"
  • "Translate all the Japanese menu text in this plugins.js file to English"
  • "This dialogue has broken line breaks — fix the formatting"

You can also select a block of text, right-click, and choose Copilot → Fix / Explain / Modify to work on just that selection.

Modifying Tool Modules

Open the DazedMTLTool folder in VSCode and ask Copilot to make changes to the translation modules. Examples:

  • "Add a new regex pattern to skip lines that start with //"
  • "Change the wordwrap logic to break on full-width punctuation"
  • "Explain what CODE 356 does in rpgmakermvmz.py"

Copilot can read the surrounding code and suggest context-aware edits — you just review and accept. This makes it easy to customize the tool for specific games without deep Python knowledge.

Tips

  • Use Ctrl+Shift+I to open Copilot Chat and ask questions about any file you have open.
  • Use Ctrl+I for inline editing — select code, describe what you want changed, and Copilot will rewrite it in place.
  • Use Git with your game folder so you can always undo changes if something breaks. The GitLens extension makes this even easier.

Version Control with Git

Git tracks every change you make to your game files, so you can compare translations against the originals and roll back mistakes. This is optional but highly recommended — it has saved countless hours of work.

Install Git

  1. Download and install Git. The default settings during installation are fine.
  2. Open a terminal and verify it's installed: git -v

Set Up Git in Your Game Folder

  1. Open your game folder (where Game.exe lives) in VSCode — right-click the folder → Open with Code.
  2. Open the terminal in VSCode (Ctrl+`` ``) and run: 
    git init
    This creates a new Git repository in that folder.

Create a .gitignore

Not every file needs to be tracked. Create a file called .gitignore in the game folder with contents like this:

# Ignore everything except text-based game files
*.*
# Allow these file types
!*.json
!*.txt
!*.js
!*.csv
!*.ks
!*.tjs
!*.rb
!*.rvdata2
# Other useful files
!.gitignore

This tells Git to only track the file types that matter for translation.

Save Your First Commit

  1. Click the Source Control icon on the left sidebar (or press Ctrl+Shift+G).
  2. You'll see all the game files listed. Type Initial Commit in the message box and click Commit → Yes (to stage all files).
  3. Your original files are now saved.

Create an "original" Branch

This lets you always compare your translated files against the untouched originals.

  1. Press Ctrl+Shift+P → type Create Branch → name it original → press Enter.
  2. Press Ctrl+Shift+P → type Checkout → select main (or master).

Now you're back on the main branch. Any translations you make here can be compared against the original branch at any time.

Comparing Changes

After translating and copying files back into the game folder:

  1. Open Source Control — you'll see all modified files listed.
  2. Click any file to see a side-by-side diff of what changed.
  3. Commit your changes with a message like Translated Items, Weapons, Actors.

To compare with the original untranslated files:

  • Right-click any file → Open Changes → Open Changes with Branch → select original.

Recommended Extension

Install GitLens (Ctrl+Shift+X → search "GitLens") for a much richer Git experience — commit history, file annotations, branch comparisons, and more.

Troubleshooting

  • START.bat closes immediately — Make sure Python 3.12–3.14 is installed and added to your PATH. Open a terminal and run python -V to check.
  • API errors — Double-check your API key and organization in .env. Make sure you have credits/quota with your provider.
  • Missing dependencies — Delete the .venv folder and run START.bat again. It will recreate the environment and reinstall everything.