### Example: Make Changes and Commit

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Example commands to stage all local changes and commit them with a message for the 'example-project'.

```git
# Make changes to the files
git add .
git commit -m "Add new feature to example project"
```

--------------------------------

### Example: Clone Forked Repository

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Example command to clone a forked repository named 'example-project'.

```git
git clone https://gitgud.io/YOUR_USERNAME/example-project.git
```

--------------------------------

### Example: Push Changes

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Example command to push changes from the 'add-new-feature' branch to your fork.

```git
git push origin add-new-feature
```

--------------------------------

### GUI Usage Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Instructions for launching the graphical user interface of the translation tool.

```bash
python start_gui.py
# or double-click START.bat on Windows
```

--------------------------------

### Example Vocab File Entries

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

This example shows the expected format for entries in the data/vocab.txt file, which provides context to the AI about game characters and terms. Entries include the Japanese name, English name in parentheses, and gender.

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

--------------------------------

### Example .env File Configuration

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Shows the format and required keys for the .env file, which configures API settings, translation parameters, and other project options.

```env
# API Configuration
api=""
key="sk-..."
organization=""
API_PROVIDER="openai"
model="gpt-4"

# Translation Settings
language="English"
timeout="120"
fileThreads="5"
threads="1"
width="60"
listWidth="100"
noteWidth="75"

# Pricing (optional; defaults used if omitted)
input_cost="0.002"
output_cost="0.002"
batchsize="10"
frequency_penalty="0.2"

# CSV Format
csvDelimiter=","

# Gemini Thinking (optional)
GEMINI_THINKING_BUDGET=""

# TL Inspector Editor
tlEditorCmd="auto"
```

--------------------------------

### Python Configuration Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/00-technical-index.md

Demonstrates how to read a configuration value from environment variables with a fallback default. The GUI and handler logic interact with this configuration.

```python
WIDTH = int(os.getenv("width", 60))  # .env env var, fallback 60
# GUI reads/writes WIDTH to .env
# Handler uses WIDTH at runtime
```

--------------------------------

### CLI Usage Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Command-line interface for running the translation tool, offering interactive modes for translation, estimation, and batch processing.

```bash
python start.py
# Interactive prompt for mode selection
# 1. Translate (live API)
# 2. Estimate (cost calculation only)
# 3. Batch Translate (Anthropic Batches API, 50% discount)
```

--------------------------------

### Example Vocabulary File

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Illustrates the format of vocab.txt for maintaining translation consistency, including character names, locations, and terms with context.

```text
# Characters
水無月 士乃 (Minazuki Shino) - Female
暗黒斎 (Dark Kokusai) - Male

# Locations
王都 (Royal Capital)
魔族の塔 (Demon Tower)

# Terms
強化 (Power-up/Enhancement)
スキル (Skill/Ability)
```

--------------------------------

### Programmatic Usage Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Demonstrates how to use the `translateAI` function and `TranslationConfig` class for programmatic translation.

```python
from util.translation import translateAI, TranslationConfig

config = TranslationConfig(
    model="gpt-4",
    language="English"
)

lines = ["こんにちは。", "元気ですか？"]
translated, tokens = translateAI(lines, translation_config=config)
print(translated)  # ['Hello.', 'How are you?']
```

--------------------------------

### Result String Format Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/03-engine-handlers-api.md

Illustrates the format of the summary string returned by all handlers, including token counts, cost, and time.

```text
FILENAME.json: [Input: 1234][Output: 567][Cost: $0.0125][1.5s] ✓
```

--------------------------------

### Run Tests Script

Source: https://github.com/dazedanon/dazedmtltool/blob/main/tests/fixtures/README.md

Execute the test suite for the project. This script handles environment setup and test execution.

```bash
./tests/run_tests.sh
```

--------------------------------

### Example Cost Calculation for Batch API

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

Illustrates the cost difference between live API usage and the discounted batch API for a specific volume of input and output tokens.

```text
Live: $3.00 + $1.50 = $4.50
Batch (50%): $2.25 + $0.75 = $3.00
Savings: $1.50 per 1M/100K
```

--------------------------------

### Custom CSV Format Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

A custom CSV format example using commas as delimiters, with columns for ID, text, and translation.

```csv
id,text,translation
1,こんにちは,Hello.
2,さようなら,Goodbye.
```

--------------------------------

### Verify Pip Installation

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Run this command in a new terminal to check if pip is installed and accessible.

```bash
pip -V
```

--------------------------------

### Instantiate TranslationConfig

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/02-util-translation-api.md

Example of creating a TranslationConfig object with specific model, language, prompt, vocabulary, batch size, and estimation mode.

```python
from util.translation import TranslationConfig

config = TranslationConfig(
    model="gpt-4",
    language="English",
    prompt="Translate Japanese to English...",
    vocab="Character names...",
    batchSize=10,
    estimateMode=False
)
```

--------------------------------

### Verify Python Installation

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Run this command in a new terminal to check if Python is installed and accessible via the PATH.

```bash
python -V
```

--------------------------------

### Batch Translation API Request Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

This is an example of the JSON payload structure for submitting translation requests to the Anthropic Batches API.

```bash
POST https://api.anthropic.com/v1/messages/batches
Authorization: Bearer $ANTHROPIC_API_KEY
Content-Type: application/json

{
  "requests": [
    {
      "custom_id": "req_001",
      "params": {
        "model": "claude-3-5-sonnet-20241022",
        "max_tokens": 1024,
        "system": [
          {"type": "text", "text": "System prompt", "cache_control": {"type": "ephemeral"}},
          {"type": "text", "text": "Vocabulary context"}
        ],
        "messages": [
          {"role": "user", "content": "Translate these 10 lines..."}
        ]
      }
    },
    ...
  ]
}
```

--------------------------------

### TranslateAI Usage Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/02-util-translation-api.md

Demonstrates translating a list of Japanese lines to English using translateAI with a pre-configured TranslationConfig object and specifying the speaker.

```python
from util.translation import translateAI, TranslationConfig

config = TranslationConfig(model="gpt-4", language="English")

lines = [
    "こんにちは。",
    "元気ですか？"
]

translated, tokens = translateAI(
    lines,
    translation_config=config,
    speaker="Protagonist",
    estimateMode=False
)

print(translated)  # ['Hello.', 'How are you?']
print(tokens)      # [45, 20]  # 45 input tokens, 20 output
```

--------------------------------

### Example Translation Log Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Shows the format of the real-time translation log file, detailing file names, token counts, costs, and processing duration for each translation.

```text
Map001.json: [Input: 1234][Output: 567][Cost: $0.0125][1.5s] ✓
Map002.json: [Input: 2345][Output: 890][Cost: $0.0235][2.1s] ✓
TOTAL: [Input: 3579][Output: 1457][Cost: $0.0360][3.6s] ✓
```

--------------------------------

### Get Model Pricing Configuration

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/02-util-translation-api.md

Retrieve the input/output costs per million tokens and the recommended batch size for a specified model. This is essential for estimating and managing translation expenses.

```python
from util.translation import getPricingConfig

config = getPricingConfig("gpt-4")
print(config)
# {
#   'inputAPICost': 30.0,
#   'outputAPICost': 60.0,
#   'batchSize': 10,
#   'frequencyPenalty': 0.2
# }
```

--------------------------------

### Define TL Inspector Installer Function

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Defines a function to install the TL Inspector plugin into an RPG Maker game. This involves copying files and registering the plugin.

```python
def install_tl_inspector(game_path: str) -> bool
```

--------------------------------

### Configure .gitignore for Translation Files

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Create a .gitignore file to specify which files Git should ignore. This example prioritizes tracking text-based game files relevant to translation.

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

--------------------------------

### Example System Prompt for Translation

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Provides a typical system prompt for AI translation tasks, instructing the AI on its role, translation style, and handling of special codes.

```text
You are a professional game translator. Translate Japanese text to English
maintaining the original tone and meaning. Keep translations natural and idiomatic.
Preserve control codes like \c[5] and \n[1] unchanged.
Follow the character and location names provided in the vocabulary.
```

--------------------------------

### Example Translation Cache Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Demonstrates the JSON format of the translation cache file, which stores previously translated strings using MD5 hashes for efficient reuse.

```json
{
  "5d41402abc4b2a76b9719d911017c592": "Hello",
  "6512bd43d9caa6e02c990b0a82652dca": "Good morning"
}
```

--------------------------------

### Example Batch API Request Structure

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Illustrates the JSON format for batch API requests, specifically for the Anthropic API's collect phase, detailing custom IDs and request parameters.

```json
[
  {
    "custom_id": "req_001",
    "params": {
      "model": "claude-3-5-sonnet-20241022",
      "max_tokens": 1024,
      "system": [...],
      "messages": [...] 
    }
  }
]
```

--------------------------------

### isClaudeModel Usage Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/02-util-translation-api.md

Shows how to use the isClaudeModel function to check if a model string is a Claude variant.

```python
isClaudeModel("claude-3-5-sonnet-20241022")  # True
isClaudeModel("gpt-4")                       # False
```

--------------------------------

### Start Batch Translation

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Initiates the batch translation process using the Anthropic Batches API. This is the entry point for translating large volumes of text at a reduced cost.

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

--------------------------------

### RPG Maker MV/MZ Translation Configuration Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/03-engine-handlers-api.md

This Python code snippet demonstrates how to configure translation options for RPG Maker MV/MZ games. It shows setting boolean flags to control which text elements are translated, such as NPC names, dialogue, and map names.

```python
CODE101 = True # Translate NPC names (code 101)
CODE401 = True # Translate dialogue (code 401)
CODE405 = True # Translate choice text (code 405)
CODE102 = True # Translate map/location names (code 102)
CODE408 = False # Translate scroll text (code 408)
CODE122 = False # Translate variable assignments (code 122)
CODE122_VAR_MIN = 0 # Min variable ID to translate (code 122)
CODE122_VAR_MAX = 2000 # Max variable ID to translate (code 122)
CODE355655 = False # Translate script regex patterns (code 355/655)
CODE357 = False # Translate plugin params (code 357)
CODE657 = False # Translate comment text (code 657)
CODE356 = False # Translate script code (code 356)
CODE320 = False # Translate input text (code 320)
CODE324 = False # Translate sound/effect (code 324)
CODE325 = False # Translate battle text (code 325)
CODE111 = False # Translate conditional branches (code 111)
CODE108 = False # Translate comments (code 108)
FIRSTLINESPEAKERS = False # Extract speaker name from first dialogue line
INLINE401SPEAKERS = False # Extract speaker from `Name「text」` format on code 401
FACENAME101 = False # Map face image file names to speaker names
# FACENAME101_MAP = (see config) # Face name → speaker name mappings
BRFLAG = False # Output newlines as `<br>` instead of `\n`
FIXTEXTWRAP = True # Rewrap text to WIDTH/NOTEWIDTH
IGNORETLTEXT = False # Skip lines already marked translated
TLSYSTEMVARIABLES = False # Translate System.json variable names
TLSYSTEMSWITCHES = False # Translate System.json switch names
JOIN408 = False # Combine code 408 continuation into single message
# ENABLED_PLUGINS_357 = set() # Plugin code 357 headers to enable (from `HEADER_MAPPINGS_357`)
# ENABLED_PATTERNS_355655 = set({"BattleManager._logWindow.addText"}) # Script patterns to enable (from `PATTERNS_355655`)
```

--------------------------------

### Example Variable Translation Map Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Shows the JSON structure for mapping variable names (e.g., CODE 122) to their English translations, ensuring consistency across dialogue and game elements.

```json
{
  "プレイヤー名": "Player Name",
  "経験値": "Experience Points"
}
```

--------------------------------

### Mistral API Configuration

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Configure the tool to use the Mistral API by setting the API provider, endpoint URL, API key, and desired model in the .env file. This setup enables direct integration with Mistral's services.

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

--------------------------------

### Batch Status Polling API Request

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

This is an example of a GET request to poll the status of a specific batch job using its ID.

```bash
GET https://api.anthropic.com/v1/messages/batches/{batch_id}
Authorization: Bearer $ANTHROPIC_API_KEY
```

--------------------------------

### Initialize a Git Repository

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Run this command in your game folder to initialize a new Git repository. This is the first step in tracking your project's changes.

```bash
git init
```

--------------------------------

### Validation Result Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

An example of a validation result tuple, showing a failed validation with specific line numbers and error messages.

```python
(
    False,
    [1, 3],
    [
        "Line 2: Empty translation for 'こんにちは'",
        "Line 4: Translation too short ('x') for 'さようなら'"
    ]
)
```

--------------------------------

### Manual Test Execution with Unittest

Source: https://github.com/dazedanon/dazedmtltool/blob/main/tests/fixtures/README.md

Manually run the unittest suite from the project root. Ensure the virtual environment is activated before execution.

```bash
cd /path/to/DazedMTLTool
source .venv/bin/activate   # or: source venv/bin/activate
python -m unittest tests.test_mvmz_source_original -v
```

--------------------------------

### DazedMTLGUI Constructor

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/04-gui-application.md

Initializes the main application window, setting up the menu bar, tab widget, status bar, and handling settings persistence. It also manages the translation thread.

```python
def __init__(self, parent=None)
```

--------------------------------

### Pricing Configuration Dictionary

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

A Python dictionary representing pricing configuration, including costs per million tokens, recommended batch size, and sampling parameters.

```python
{
    "inputAPICost": 30.0,          # Per 1M tokens
    "outputAPICost": 60.0,         # Per 1M tokens
    "batchSize": 10,               # Recommended batch size
    "frequencyPenalty": 0.2        # Sampling parameter
}
```

--------------------------------

### translateAI Input Parameters

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

Illustrates the parameters for the `translateAI` function, showing both simple line input and detailed configuration with a `TranslationConfig` object. Optional context parameters like speaker and history are also included.

```python
# Simple form
lines: list[str] = [
    "こんにちは。",
    "元気ですか？"
]

# With configuration
translation_config: TranslationConfig = TranslationConfig(
    model="gpt-4",
    language="English",
    prompt="Translate Japanese...",
    vocab="Character names...",
    batchSize=10,
    estimateMode=False
)

# Optional context
speaker: str = "Protagonist"
historical_context: str = "Previous scene background..."
speaker_history: str = "Previous dialogue from speaker..."
```

--------------------------------

### Prompt Configuration (prompt.txt)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

System prompt content for AI translation tasks.

```text
System prompt for AI translation...
```

--------------------------------

### Checkout the Main Branch

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Use this command to switch back to the main branch (or master) after creating the 'original' branch. Translations are typically made on this branch.

```bash
git checkout main
```

--------------------------------

### Anthropic Batches API Response Example

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

This JSON object represents the initial response from the Anthropic Batches API after a batch submission, indicating its queued status.

```json
{
  "id": "batch_...",
  "type": "batch",
  "processing_status": "queued",
  "request_counts": {
    "processing": 500,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "created_at": "2024-06-13T12:00:00Z",
  "expires_at": "2024-06-20T12:00:00Z"
}
```

--------------------------------

### Environment Variables: Text Formatting

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variables for controlling text output width. Adjust these to fit different display or output requirements.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `width` | int | `60` | `50` |
| `listWidth` | int | `100` | `80` |
| `noteWidth` | int | `75` | `70` |
```

--------------------------------

### Environment Variables: Custom Pricing

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variables for setting custom input/output costs, batch size, and frequency penalty. Useful for fine-tuning cost calculations.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `input_cost` | float | `0.002` | `0.0003` |
| `output_cost` | float | `0.002` | `0.0006` |
| `batchsize` | int | `10` | `20` |
| `frequency_penalty` | float | `0.2` | `0.5` |
```

--------------------------------

### File Permissions: Write Locations

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Details the locations where the tool is expected to write files, including translated outputs, logs, caches, and the virtual environment.

```text
- `translated/` — Translated output files
- `log/` — All cache and log files
- `.venv/` — Virtual environment (auto-created)
```

--------------------------------

### getPricingConfig

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/02-util-translation-api.md

Retrieves input/output costs and recommended batch size for a specified model.

```APIDOC
## getPricingConfig

### Description
Get input/output costs and batch size for a model.

### Method
```python
def getPricingConfig(model: str) -> dict
```

### Parameters
#### Path Parameters
- **model** (str) - Required - Model identifier

### Response
#### Success Response (dict)
- **inputAPICost** (float) - Input cost per 1M tokens
- **outputAPICost** (float) - Output cost per 1M tokens
- **batchSize** (int) - Recommended batch size (lines per request)
- **frequencyPenalty** (float) - Sampling parameter (0.0–2.0)

### Example
```python
from util.translation import getPricingConfig

config = getPricingConfig("gpt-4")
print(config)
# {
#   'inputAPICost': 30.0,
#   'outputAPICost': 60.0,
#   'batchSize': 10,
#   'frequencyPenalty': 0.2
# }
```
```

--------------------------------

### Translator++ CSV Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

Example of the Translator++ CSV format, using tabs as delimiters and specific columns for ID, speaker, source text, target text, and notes.

```csv
(ID)	(Speaker)	Japanese text	English text	(Notes)
1	Alice	こんにちは	Hello.	—
2	Bob	元気ですか？	How are you?	—
```

--------------------------------

### Repository Structure

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Overview of the DazedMTLTool project's directory structure, highlighting key modules and configuration files.

```tree
DazedMTLTool/
├── modules/              # 17 engine-specific handlers
├── gui/                  # PyQt5 application (10 tabs)
├── util/                 # Shared utilities (translation, caching, etc.)
├── files/                # Input game files
├── translated/           # Output translation results
├── log/                  # Caches, logs, batch data
├── start.py              # CLI entry point
├── start_gui.py          # GUI launcher
├── .env                  # Configuration (required)
├── prompt.txt            # System prompt (required)
├── vocab.txt             # Vocabulary reference (optional)
└── README.md             # User guide
```

--------------------------------

### Partial System.json Structure

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

A partial view of the system configuration JSON structure, showing common keys like variables, switches, map names, and game title.

```json
{
  "variables": ["", "Variable1", "Variable2", ...],
  "switches": ["", "Switch1", "Switch2", ...],
  "mapNames": ["", "Map Name 1", "Map Name 2", ...],
  "gameTitle": "Game Title",
  "currencyUnit": "$",
  ...
}
```

--------------------------------

### Performance Configuration: Cost Optimization

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Strategies for optimizing costs, including increasing batch size, reducing file threads, enabling IGNORETLTEXT, and using batch mode for Anthropic.

```text
- Increase `batchsize` (default 10) → fewer API calls
- Reduce `fileThreads` (default 5) → limit concurrent file streams
- Enable `IGNORETLTEXT` → skip already-translated lines
- Use batch mode → 50% cost reduction on Anthropic
```

--------------------------------

### DazedMTLTool Folder Structure

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

An overview of the project's directory structure, indicating the purpose of each main folder and key configuration files.

```text
DazedMTLTool/
├── files/                    # Input game files (place here)
├── translated/               # Output translated files
├── log/                       # Logs and caches
│   ├── translations.txt
│   ├── translation_cache.json
│   ├── var_translation_map.json
│   ├── batch_requests.json
│   ├── batch_results.json
│   ├── estimate_written_sizes.json
│   ├── litellm_pricing.json
│   ├── request_debug.log
│   └── mismatchHistory.txt
├── modules/                  # Engine handlers
├── gui/                       # PyQt5 GUI
├── util/                      # Shared utilities
├── .env                       # Configuration (required)
├── prompt.txt                 # AI system prompt (required)
├── vocab.txt                  # Vocabulary reference
├── vocab_base.txt             # Base vocabulary template
├── requirements.txt           # Python dependencies
├── start.py                   # CLI entry point
├── start_gui.py               # GUI launcher
├── START.bat                  # Windows batch launcher
└── README.md                  # Documentation
```

--------------------------------

### Run Database Original Fixture Tests

Source: https://github.com/dazedanon/dazedmtltool/blob/main/tests/fixtures/README.md

Execute the test suite specifically for the database `_original` fixtures. This verifies scalar field preservation in database JSON files.

```bash
./tests/run_tests.sh tests.test_mvmz_db_original -v
```

--------------------------------

### Environment Variables: Tools

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variable for specifying the command to launch an external text editor. Defaults to 'auto'.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `tlEditorCmd` | str | `auto` | `/usr/bin/code` |
```

--------------------------------

### Environment Variables: Connection Settings

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variables for network connection parameters like timeout and thread counts. Tune these for optimal network performance.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `timeout` | int | `120` | `60` |
| `fileThreads` | int | `5` | `1` |
| `threads` | int | `1` | `2` |
```

--------------------------------

### File Permissions: Required for Execution

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Specifies the minimum file and directory permissions required for the tool to execute correctly, covering configuration, input, output, and log files.

```text
- `.env` — Read (API configuration)
- `prompt.txt` — Read (system prompt)
- `vocab.txt` — Read (vocabulary)
- `files/` — Read (input files)
- `translated/` — Write (output files)
- `log/` — Read/Write (cache and logs)
```

--------------------------------

### Clone Repository

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Clone your forked repository to your local machine using Git. Replace YOUR_USERNAME and REPO_NAME with your specific details.

```git
git clone https://gitgud.io/YOUR_USERNAME/REPO_NAME.git
```

--------------------------------

### Vocabulary Configuration (vocab.txt)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Optional file for specifying character names, terms, and context to improve translation accuracy.

```text
Character names, terms, and context...
```

--------------------------------

### Environment Configuration (.env)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/README.md

Required environment variables for API access, model selection, and translation settings.

```env
api=""
key="your-api-key"
organization=""
API_PROVIDER="openai"
model="gpt-4"
language="English"
timeout="120"
fileThreads="5"
threads="1"
width="60"
listWidth="100"
noteWidth="75"
```

--------------------------------

### Batch State Machine Diagram

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

Visual representation of the batch processing states, from initial queuing to completion.

```text
┌─────────┐
│  queued │  Initial state after submission
└────┬────┘
     │
     ↓
┌──────────────┐
│ in_progress  │  Processing ongoing
└────┬─────────┘
     │ (all requests finish)
     ↓
┌───────────┐
│ completed │  Ready to fetch results
└───────────┘

```

--------------------------------

### Environment Variables: Model Settings

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variables for specifying the model, language, and Gemini's thinking budget. Adjust these based on your specific needs.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `model` | str | — | `gpt-4` |
| `language` | str | `English` | `Spanish` |
| `GEMINI_THINKING_BUDGET` | int | (empty) | `8192` |
```

--------------------------------

### ConfigTab Class Definition

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/04-gui-application.md

Represents the configuration tab within the DazedMTLGUI. This class inherits from QWidget and manages settings for API configuration and translation parameters.

```python
class ConfigTab(QWidget)
```

--------------------------------

### Run Game Update Script (Linux)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Execute the GameUpdate_linux.sh script to automatically patch the game on Linux systems. Ensure the script is placed in the game root directory.

```shell
GameUpdate_linux.sh
```

--------------------------------

### RPG Maker Map Event Structure (Partial)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

Shows a partial structure of a `Map*.json` file used in RPG Maker, detailing an event's properties and its list of commands, including dialogue and choices.

```json
[
  null,
  {
    "id": 1,
    "name": "Event Name",
    "x": 10,
    "y": 5,
    "pages": [
      {
        "conditions": {...},
        "image": {...},
        "list": [
          {
            "code": 101,
            "indent": 0,
            "parameters": ["NPC Name", 0, 0, 2]
          },
          {
            "code": 401,
            "indent": 0,
            "parameters": ["First line of dialogue"]
          },
          {
            "code": 401,
            "indent": 0,
            "parameters": ["Second line of dialogue"]
          },
          {
            "code": 405,
            "indent": 0,
            "parameters": ["Choice 1", "Choice 2"]
          }
        ]
      }
    ]
  }
]
```

--------------------------------

### RPG Maker MV/MZ Translation Flow

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/01-modules-overview.md

Illustrates the steps involved in translating an RPG Maker MV/MZ JSON file, from parsing to AI translation and saving.

```python
modules.main.MODULES[0]  # ["RPGMaker MV/MZ", ["json"], handleMVMZ]
  ↓
handleMVMZ("Map001.json", estimate=False)
  ↓
  openFiles("Map001.json")  # Parse JSON
  ↓
  parseMap(data)            # Extract dialogue codes (401, 405, 408, 101)
  ↓
  translateAI(lines, ...)   # Batch translate with util.translation
  ↓
  saveProgress(data)        # Write to translated/Map001.json
```

--------------------------------

### Create an 'original' Git Branch

Source: https://github.com/dazedanon/dazedmtltool/blob/main/README.md

Use this command to create a new branch named 'original'. This branch will store the untranslated game files, allowing for easy comparison later.

```bash
git checkout -b original
```

--------------------------------

### CLI Batch Mode Interactive Prompt

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/07-batch-api-and-workflow.md

Demonstrates the interactive prompts when selecting and initiating a batch translation job via the command line interface.

```bash
Select Mode:

 1. Translate
 2. Estimate
 3. Batch Translate (Anthropic Batches API, 50% off)

```

```bash
Selected: Batch Translate

Select Engine:
[List of engines...]

Select Engine [0-15]:

```

```bash
Collecting requests from selected files...
[████████████████] 100% | 500/500 files processed

Batch Queue Statistics:
  Files: 500
  Requests queued: 1,234
  Estimated input tokens: 1,234,567
  Estimated output tokens: 123,456
  
Cost Estimation:
  Batch mode (50% discount): $20.36
  Live mode (full price): $40.71
  
Proceed with batch submission? [y/n]:

```

```bash
y

Submitting batch to Anthropic...
Batch ID: batch_abc123def456

Polling for completion... (Ctrl+C to stop and resume later)
Status: in_progress [████░░░░░░] 40% | 200/500 requests

Estimated completion: ~5 minutes

```

```bash
Batch completed in 3 minutes 45 seconds!

Results Summary:
  Succeeded: 1,230/1,234 (99.7%)
  Failed: 4
  Fallback to live API: 4

Consuming results... (applying translations to files)
[████████████████] 100% | 500/500 files written

Final Cost Report:
  Input tokens (actual): 1,234,123
  Output tokens (actual): 123,789
  Cache writes: 500 * 456 = 228,000 tokens (at 2x rate)
  Cache reads: 1,200 * 456 = 547,200 tokens (at 0.1x rate)
  
  Batch cost (50%): $20.28
  Breakdown:
    - Input: (1,234,123 * $0.003 / 1M) * 0.5 = $1.85
    - Output: (123,789 * $0.015 / 1M) * 0.5 = $0.93
    - Cache write: (228,000 * $0.003 * 2 / 1M) * 0.5 = $0.68
    - Cache read: (547,200 * $0.003 * 0.1 / 1M) * 0.5 = $0.08

Translation complete! Files written to: translated/

```

--------------------------------

### scan_project_folder

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Recursively scans a game project folder to gather file metadata and project information.

```APIDOC
## scan_project_folder

### Description
Recursively scan game folder for data files.

### Method Signature
```python
def scan_project_folder(path: str) -> dict
```

### Parameters
#### Parameters
- **path** (str) - Required - The path to the game project folder.

### Returns
`dict` — A dictionary containing file structure and metadata.

### Detected Information
- Engine type (RPG Maker, Wolf, Ren'Py, etc.)
- File extensions present
- Folder structure
- Estimated translation volume
```

--------------------------------

### Run Game Update Script (Windows)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Execute the GameUpdate.bat script to automatically patch the game on Windows. Ensure the script is placed in the game root directory.

```batch
GameUpdate.bat
```

--------------------------------

### Environment Variables: API & Authentication

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variables for API endpoints, keys, and provider selection. Ensure API keys are kept secure.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `api` | str | — | `https://integrate.api.nvidia.com/v1/` |
| `key` | str | — | `sk-proj-...` |
| `organization` | str | — | `org-...` |
| `API_PROVIDER` | str | `openai` | `gemini` |
```

--------------------------------

### Add and Commit Changes

Source: https://github.com/dazedanon/dazedmtltool/blob/main/gameupdate/README.md

Stage all changes and commit them with a descriptive message. This is part of the contribution workflow.

```git
git add .
git commit -m "Description of your changes"
```

--------------------------------

### Text Wrapping Utility

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/03-engine-handlers-api.md

Wraps text to a specified width, preserving RPG Maker color codes.

```python
def wrapText(text: str, width: int) -> str
```

--------------------------------

### DazedMTLGUI Class Definition

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/04-gui-application.md

Defines the main application window for the DazedMTLTool GUI. It inherits from QMainWindow and serves as the central hub for all translation-related functionalities.

```python
class DazedMTLGUI(QMainWindow)
```

--------------------------------

### Performance Configuration: Speed Optimization

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Strategies for improving processing speed, such as increasing file and API threads, and reducing output token length. Caching is enabled by default.

```text
- Increase `fileThreads` → parallel file processing
- Increase `threads` → more API calls per file (rate-limit dependent)
- Reduce `width` → shorter output tokens
- Cache enabled (default) → reuse translations
```

--------------------------------

### Update Tracking File Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

This plain text file stores the last downloaded commit SHA, used for checking for updates.

```text
a1b2c3d4e5f6g7h8i9j0
```

--------------------------------

### Environment Variables: CSV Format

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/05-utilities-and-config.md

Configuration variable for specifying the delimiter used in CSV output. Defaults to a comma.

```text
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `csvDelimiter` | str | `,` | `\t` |
```

--------------------------------

### Structured Description Text Wrapping Utility

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/03-engine-handlers-api.md

Specialized wrapper for structured plugin descriptions, preserving bullet points and headers.

```python
def wrapSGDesc(text: str, width: int) -> str
```

--------------------------------

### RPG Maker Actors.json Structure (Partial)

Source: https://github.com/dazedanon/dazedmtltool/blob/main/_autodocs/06-types-and-schemas.md

Presents a partial structure of an `Actors.json` file for RPG Maker, outlining the basic properties of an actor, such as ID, name, nickname, and class.

```json
[
  null,
  {
    "id": 1,
    "name": "Actor Name",
    "nickname": "Nickname",
    "description": "Actor description",
    "classId": 1,
    ...
  }
]
```