# Overview

Welcome to the VNTranslator Docs!

<figure><img src="/files/U08BlCyJlbrY5lmIc1gi" alt=""><figcaption></figcaption></figure>

This documentation provides comprehensive guidance on using VNTranslator to translate visual novels and PC games.

If you're looking to perform a specific workflow, check out the sections below to find the right tools and guides.

## Getting Started

To begin using VNTranslator, refer to the [Getting Started](/getting-started/getting-started) section.

{% content-ref url="/pages/mWadSoPjrekvb7Qa5H5T" %}
[Getting Started](/getting-started/getting-started)
{% endcontent-ref %}

***

## Clipboard Translator&#x20;

The Clipboard Translator provides quick and automatic translation. It detects text copied to your clipboard and instantly displays the translation in the [Extra Window](/features/extra-window).

Learn more about [Clipboard Translator](/user-guide/clipboard)

***

## OCR Translator

The OCR Translator extracts text directly from your screen using Optical Character Recognition (OCR) and translates it. This feature includes advanced options such as [pre-processing](/user-guide/ocr/pre-processing), [post-processing](/user-guide/ocr/post-processing), and support for multiple [OCR engines](/user-guide/ocr/ocr-engines).

Learn more about [OCR Translator](/user-guide/ocr)

***

## AutoTrans

AutoTrans is an exclusive feature that provides real-time translation of in-game text. It automatically detects and translates game dialogue as you play.

Learn more about [AutoTrans](/user-guide/autotrans)

***

## TextractorCLI & XUAT Integration

VNTranslator supports the following third-party integrations:

* [**TextractorCLI**](/user-guide/textractorcli) is a text hooker that extracts in-game text and sends it to VNTranslator for translation. The translated text is displayed in the [Extra Window](/features/extra-window)
* [**XUAT**](/user-guide/unity-games) (XUnity.AutoTranslator) is used to translate Unity-based games in real-time.\
  Text extracted by XUAT is sent to VNTranslator for translation, then returned to XUAT to be displayed directly in the game.

***

## ~~RenPy Script~~ (Deprecated)

A legacy feature for translating RenPy-based games.

{% hint style="danger" %}
This feature is no longer actively maintained or supported.
{% endhint %}


# Getting Started

This guide walks you through the initial setup and basic usage of VNTranslator.

<div align="left"><figure><img src="/files/joB7cwhas6GkEzJejNkm" alt=""><figcaption></figcaption></figure></div>

{% stepper %}
{% step %}

### Install the App

If you haven't installed VNTranslator yet, refer to the [Download & Installation](/getting-started/download-and-installation) section.
{% endstep %}

{% step %}

### Launch VNTranslator

After installation:

* Open **VNTranslator**
* The **VNTranslator Launcher** window will appear
  {% endstep %}

{% step %}

### Configure Translation Settings

Configure the translator and languages:

* Click **Translator** in the menu bar and select a **Translation Service**
* Select the **Source Language**
* Select the **Target Language**
  {% endstep %}

{% step %}

### Basic Usage

**Quick Start Example: Using Clipboard**

* Select **Clipboard** from the module list&#x20;
* Select **Extra Window** from the output list&#x20;
* Click the **Start** button&#x20;
* Copy any text - the translation appears automatically
  {% endstep %}
  {% endstepper %}

***

## Launcher Interface

The launcher interface is divided into three main sections:

#### **Menu Bar (Top Section)**

* **App icon** (left corner):
  * Translation Editor - Edit and manage translations
  * Settings - Open settings
  * Relaunch - Relaunch the app
  * Exit - Close the app
* **Translator** - Configure and select translation services
* **Glossary** - Manage custom translation dictionaries
* **About** - App information and version details

#### **Translation Control (Middle Section)**

* **Source Language** - Select the language to translate from
* **Start Button** - Begin or stop the translation process
* **Target Language** - Select the language to translate to

#### **Module Configuration (Bottom Section)**

* **Settings button** (left corner) - Open module settings
* **Module Selection**\
  Choose the input method from the module list:
  * [**Clipboard**](/user-guide/clipboard) **-** Translate text copied to your clipboard
  * [**OCR**](/user-guide/ocr) **-** Capture and translate text from your screen (images/games)
  * [**AutoTrans**](/user-guide/autotrans) **-** Automatically translate text directly in games
* **Module Options**\
  These settings vary depending on the selected module:
  * **Clipboard**: No additional options required
  * **OCR**: Select an OCR engine and language
  * **AutoTrans**: Click Browse and select the game executable file
* **Output Options**

  Available output methods vary by module:

  * **Clipboard**: [Extra Window](/features/extra-window)
  * **OCR**: [Extra Window](/features/extra-window) or [Hyper Overlay](/features/hyper-overlay)
  * **AutoTrans**: In-game injection (displays translated text directly in the game)
* **Logs button** (right corner) - Open logs folder


# System Requirements

### Recommended Specifications

<table><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><strong>Operating System</strong></td><td>Windows 11 (64-bit) or Windows 10 (64-bit)</td></tr><tr><td><strong>CPU</strong></td><td>Intel Core i5 / AMD Ryzen 5 or higher</td></tr><tr><td><strong>RAM</strong></td><td>16 GB or more</td></tr><tr><td><strong>Storage</strong></td><td>At least 1 GB available space (SSD recommended)</td></tr><tr><td><strong>GPU</strong></td><td>Graphics card compatible with OpenGL 2.1 or newer</td></tr><tr><td><strong>Display</strong></td><td>Minimum 1366 x 768 resolution</td></tr><tr><td><strong>Network</strong></td><td>Internet connection required for online translation engines</td></tr></tbody></table>

### Minimum Specifications

<table><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><strong>Operating System</strong></td><td>Windows 10 (64-bit)</td></tr><tr><td><strong>CPU</strong></td><td>Intel Core i3 / AMD Ryzen 3</td></tr><tr><td><strong>RAM</strong></td><td>8 GB</td></tr><tr><td><strong>Storage</strong></td><td>1 GB available space</td></tr><tr><td><strong>GPU</strong></td><td>OpenGL 2.1 compatible graphics card</td></tr><tr><td><strong>Display</strong></td><td>1366 x 768 resolution</td></tr></tbody></table>


# Download & Installation

## Downloads

* **PRO Version**\
  <https://www.patreon.com/vntranslator>
* **Public Version**\
  <https://fazx.itch.io/visual-novel-translator>

***

## Installation Guide

Before installing VNTranslator, please ensure that you have the latest version of the Visual C++ Redistributable (vcredist) installed and updated on your operating system.

You can download the Visual C++ Redistributable from the official Microsoft website:

* Download Link: [**Visual C++ Redistributable**](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)

## How to Install VNTranslator

* Download the installer
* Run the installer file and follow the on-screen instructions
* Choose the installation directory.\
  It is recommended to install VNTranslator for all users at: `(C:\Program Files\VNTranslator)`
* Complete the installation process and launch VNTranslator


# Translation

### **Spam Prevention with Queueing and Delay System**

VNTranslator uses a built-in queue system with configurable delays to prevent sending too many requests to translation services. When using free translation services, this feature keeps translation requests within safe limits and prevents IP or account blocking due to excessive requests.

### **Translation Memory**

Translation Memory stores previously translated text and automatically reuses it when the same text appears again, preventing duplicate translation requests and saving time and resources.

### **Translation Glossary**

Define custom translations for specific terms or character names to maintain consistency throughout the game.

### **Pre-translation Features**

This feature helps clean and prepare the original text before sending it for translation.

* **Allow line breaks**: Preserves or removes line breaks from the original text
* **Trim & normalize spaces**: Removes extra whitespace to ensure clean input
* **Exclude strings**: Prevents specific text from being translated
* **RegExp (Regular Expressions)**: Define patterns for matching and replacing text before translation

### **Post-translation Features**

After translation is complete, this feature allows you to modify the translation results.

* **Auto line break matching**: Automatically matches line breaks in the translated text to the original formatting
* **RegExp (Regular Expressions)**: Define patterns for matching and replacing text after translation

### **Context Memory Support in LLM**

When using Large Language Models (LLMs), VNTranslator maintains context memory, allowing the model to reference previous dialogue. This improves translation quality and coherence, especially for conversations.

### **Text Streaming Support in LLM**

Displays translations progressively as they are generated instead of waiting for completion. This makes the translation process faster and more responsive.

### **Edit and Delete Translations**

Manually edit or delete any translation.

### **Exporting and Importing Translations**

Export and import translation files for backup or sharing.

### **TransCheck (Translation Checker)**

Compares source text with translations and highlights inconsistencies or missing content to ensure accuracy and completeness.


# General Settings

<figure><img src="/files/pt6JgOmT20npmSEgFbgD" alt=""><figcaption></figcaption></figure>

## Translation Requests

### Request mode&#x20;

<div align="left"><figure><img src="/files/PSDKTYfGcGuSh4VTJfd5" alt=""><figcaption></figcaption></figure></div>

Choose how translation requests are processed:

<table><thead><tr><th width="200.4000244140625">Mode</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td>Offline</td><td>Disables all translation requests</td><td></td></tr><tr><td>MT-only</td><td>Uses Machine Translation only</td><td></td></tr><tr><td>TM-only</td><td>Uses Translation Memory only</td><td></td></tr><tr><td>TM or MT</td><td>Checks Translation Memory first, then falls back to Machine Translation if no match is found</td><td></td></tr><tr><td>TM and MT</td><td>Queries both Translation Memory and Machine Translation. Displays TM results immediately if available, then updates with MT results. MT translations are saved to TM automatically</td><td></td></tr></tbody></table>

### Request delay

Adds a delay (in milliseconds) before sending requests to Machine Translation.

### Max worker processes

Sets the number of concurrent workers for processing translation requests.

{% hint style="danger" %}
Caution: Higher worker counts may trigger rate limiting or IP blocks from translation services.
{% endhint %}

### URL encoding

Configures URL encoding for Machine Translation requests.

### Text streaming

Enables progressive text display for AI/LLM translations.

### Stream adapter

Configures streaming behavior for AI/LLM services.

***

## Queue Management

### Enable queue

Enables the translation queue system to prevent spam. Enabled by default.

{% hint style="info" %}
The queue feature is always enabled and cannot be disabled as it is part of the spam prevention system to avoid sending excessive requests to translation services. As a result, when you frequently play with CTRL (skipping text), translations will build up in the queue. You can reduce the **Max queue** value to limit the number of queued translations.
{% endhint %}

### Max queue length

Sets the maximum queue length.


# Translation Memory

Translation Memory (TM) stores previously translated text for automatic reuse. Enabled by default.

### Enable translation memory

Enables or disables Translation Memory.

### Smart Matching

{% hint style="info" %}
Smart Matching is enabled by default when using AutoTrans.\
When a translation is marked as DNT (Do Not Translate), any text matching that pattern returns the source text without translation.
{% endhint %}

Smart Matching prevents unnecessary translation of text with dynamic patterns, commonly found in RPGM games and visual novels.

**Example:** Without Smart Matching, these three texts would require 3 separate translations:

* Gold: 1001
* Gold: 2002
* Gold: 3003

With Smart Matching enabled, only 1 translation is needed.

### Auto-save interval

Automatically saves Translation Memory to disk at specified intervals.

### Split translation memory

Splits Translation Memory into multiple files when size or entry limits are reached.

### Max split size (MB)

Maximum file size (in MB) before splitting Translation Memory.

### Max split entries

Maximum number of entries before splitting Translation Memory.

### Max search results

Maximum number of results returned from Translation Memory searches.

***

## Personal Memory

Personal Memory differs from the default Translation Memory by supporting Fuzzy Matching, where you can configure the text match score threshold.

**Key Differences:**

* **Default Translation Memory:** Uses exact matching for accurate and fast translation retrieval
* **Personal Memory:** Offers more flexibility with fuzzy matching capabilities

**How to add entries:**

* From Translation Editor. You can add entries manually, or
* Copy entries from Translation Memory by right-clicking and selecting "Add to Personal"

**Use cases:**

* Store translations for game menu/UI text
* Maintain a list of common item translations
* No need to import/export from Translation Memory, as it uses separate storage

{% hint style="info" %}
**Performance Note:** Adding more than 2,500 entries is not recommended, as fuzzy matching can impact performance.
{% endhint %}

### Enable personal memory

Enables or disables Personal Memory.

### Personal memory threshold

{% hint style="info" %}
**Recommended setting:** 85 to 95 for optimal balance between flexibility and accuracy.
{% endhint %}

Sets the minimum similarity score required for fuzzy matching results.


# Pre-translation

Configure text processing rules applied before sending text to the translation engine.

### Allow line breaks

Preserves line breaks in the original text. By default, all line breaks are removed before translation.

### Trim & normalize spaces

Removes leading and trailing whitespace from text before translation.

### Exclude strings

Excludes specific strings from translation. When text matches exactly, it will not be translated. However, sentences containing these strings will still be translated.

<figure><img src="/files/bk3MfyXyNAVNMHqMUKKU" alt=""><figcaption></figcaption></figure>

**Example**

Exclude Strings: `"Sunny, Summer, Dark Lord"`

<table><thead><tr><th width="200.20001220703125">Original Text</th><th>Translation Behavior</th></tr></thead><tbody><tr><td>Summer</td><td>❌ Will not be translated (exact match)</td></tr><tr><td>Where are you, Summer?</td><td>✅ Will be translated (part of sentence)</td></tr><tr><td>Hi, Summer</td><td>✅ Will be translated (part of sentence)</td></tr></tbody></table>

{% hint style="info" %}
To prevent specific terms from being translated within sentences, use the [**Translation Glossary**](/features/translation/glossary) feature with **"Define Variables"** mode
{% endhint %}

### Regular expression (RegExp)

Applies custom regular expression patterns to filter or modify text before translation.

**Learn more:** [RegExp Guide](/advanced/regexp)


# Post-translation

Configure text processing rules applied after receiving translations from the translation engine.

### Auto line break matching

Automatically adjusts line breaks in translated text to match the original formatting. Choose from different matching modes based on your needs.

**Example**

**Source Text / Original Text:**

```
Lorem Ipsum is simply dummy text of the printing and
typesetting industry. Lorem Ipsum has been the
industry's standard dummy text ever since the 1500s,
when an unknown printer took a galley of type and scrambled
it to make a type specimen book. 
```

**Normal:**

```
Lorem Ipsum hanyalah contoh teks dalam industri percetakan
dan penataan huruf. Lorem Ipsum telah menjadi contoh teks
standar industri sejak tahun 1500-an, ketika seorang pencetak
yang tidak dikenal mengambil kumpulan huruf dan mengacaknya
untuk dijadikan buku contoh huruf. 
```

**Loose:**

```
Lorem Ipsum hanyalah contoh teks dalam industri percetakan
dan penataan huruf. Lorem Ipsum telah menjadi contoh
teks standar industri sejak tahun 1500-an, ketika
seorang pencetak yang tidak dikenal mengambil kumpulan
huruf dan mengacaknya untuk dijadikan buku contoh
huruf. 
```

A**nywhere:**

```
Lorem Ipsum hanyalah contoh teks dalam industri percetakan d
an penataan huruf. Lorem Ipsum telah menjadi contoh teks sta
ndar industri sejak tahun 1500-an, ketika seorang pencetak y
ang tidak dikenal mengambil kumpulan huruf dan mengacaknya u
ntuk dijadikan buku contoh huruf. 
```

### Regular expression (RegExp)

Applies custom regular expression patterns to modify or filter translated text.

**Learn more:** [RegExp Guide](/advanced/regexp)


# Glossary

A translation glossary allows you to define specific terms or character names that should always be translated the same way. This ensures consistent terminology throughout the entire game.

A translation glossary allows you to define specific terms or character names that should always be translated the same way. This ensures consistent terminology throughout the entire game.

<figure><img src="/files/RtiniFtnks3yS9EOVWXZ" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
This is a local glossary feature, it does not yet support MT glossary.
{% endhint %}

### **Glossary mode**

Set the translation glossary mode (**Settings** → **Translation** → **Processing & Quality** → **Glossary Mode)**

* **Find & Replace:** Automatically finds and replaces terms during pre-translation.
* **Define Variables:** Defines variables during pre-translation and replaces them with glossary terms during post-translation.

***

### Create a New Glossary

To create a new glossary:

* Click **Create Glossary**
* Enter a **Name** for the glossary
* Click **Save**. Your glossary will appear in the list of available glossaries
* Click the **Glossary Name** to add terms

***

### Creating a Glossary with pinovel.net

{% hint style="info" %}
**Note**: VNDB is the main database for visual novels. pinovel.net offers a convenient Character Export feature that lets you generate glossaries quickly, without having to select and copy each character name manually.
{% endhint %}

To create a glossary for visual novels:

1. Find your visual novel on VNDB (Example: `https://vndb.org/v54132`)
2. Open the same page on **pinovel.net**, simply change `vndb.org` to `pinovel.net` in the URL:\
   `https://pinovel.net/v54132`
3. Click **Export Characters** button in the top-right corner of the character list section
4. Customize the export format field based on your needs
5. Click the **Glossary** button to generate a glossary compatible with VNTranslator format

### Example Glossary Terms

{% hint style="info" %}
Format: `SourceText, TargetText, Description(Optional)`
{% endhint %}

```
常陸 茉子, Hitachi Mako
レナ・リヒテナウアー, Lena Liechtenauer
ムラサメ, Murasame
朝武 芳乃, Tomotake Yoshino
中条 比奈実, Chuujou Hinami
猪谷 心子, Inotani Motoko
駒川 みづは, Komagawa Mizuha
鞍馬 玄十郎, Kurama Genjuurou
鞍馬 小春, Kurama Koharu
鞍馬 廉太郎, Kurama Rentarou
馬庭 芦花, Maniwa Roka
朝武 秋穂, Tomotake Akiho
朝武 安晴, Tomotake Yasuharu

```


# Transcheck

Validates translations by comparing source and translated text for inconsistencies, missing elements, and formatting issues. Helps ensure translation accuracy and completeness.

### Validation Level

* **Off -** Disables all validation checks.
* **Warning -** Displays warning messages for detected issues but continues translation.
* **Error -** Displays error messages and pauses the translation process until issues are resolved.

### Source Text Validation

Validates the source text before translation to catch potential issues.

* **Non-ASCII Characters**\
  Detects characters outside the standard ASCII character set (characters beyond basic Latin alphabet and common symbols).
* **Invalid CJK Characters**\
  Identifies invalid or corrupted characters in Chinese, Japanese, and Korean text.
* **JPN Special Characters**\
  Detects special characters specific to the Japanese writing system that may require special handling.
* **Missing Brackets**\
  Checks for unmatched or missing opening/closing brackets in the source text.

### Target Text / Translation Validation

Compares source text with translated text to ensure consistency and completeness.

* **Tags**\
  Validates that formatting tags are preserved in translation.\
  Supported formats: `{any}, [any], <any>`
* **Variables**\
  Checks that variables are properly maintained in translation.\
  Supported formats:  `%any, $any`
* **Numbers**\
  Ensures numeric values `[0-9]` are correctly transferred from source to translation.
* **Leading and trailing spaces**\
  Validates leading and trailing spaces match between source and translation to maintain formatting.

### Issue Types

TransCheck can detect the following issues:

**Source Text Issues:**

* <mark style="color:$warning;">Non-ASCII char</mark> - Character outside ASCII range detected
* <mark style="color:$warning;">Invalid CJK char</mark> - Corrupted or invalid CJK character found
* <mark style="color:$warning;">JPN special char</mark> - Special Japanese character requiring attention
* <mark style="color:$warning;">Missing bracket</mark> - Unmatched opening or closing bracket

**Translation Issues:**

* <mark style="color:$warning;">Missing Tag</mark> - Tag present in source but missing in translation
* <mark style="color:$warning;">Extra Tag</mark> - Tag in translation not found in source
* <mark style="color:$warning;">Missing variable</mark> - Variable present in source but missing in translation
* <mark style="color:$warning;">Extra variable</mark> - Variable in translation not found in source
* <mark style="color:$warning;">Missing number</mark> - Numeric value present in source but missing in translation
* <mark style="color:$warning;">Extra number</mark> - Numeric value in translation not found in source
* <mark style="color:$warning;">Inconsistent leading spaces</mark> - Leading whitespace doesn't match between source and translation
* <mark style="color:$warning;">Inconsistent trailing spaces</mark> - Trailing whitespace doesn't match between source and translation


# Variables

Configure dynamic variables used in translation requests, including context memory for AI/LLM translations.

Configure dynamic variables used in translation requests, including context memory for AI/LLM translations.

## Context memory

{% hint style="info" %}
**Note:** This is a manual variable configuration for **Custom MT.**\
**In VNTranslator versions >= v0.8.8**, context memory is automatically applied to all AI/LLM API services, so manual configuration is not required.
{% endhint %}

Maintains context history for AI/LLM translations, allowing the model to reference previous dialogue for improved coherence and accuracy. Customize the system prompt and control how much context is retained.

<figure><img src="/files/r2puB4uBvu6tb9lp3xPq" alt=""><figcaption></figcaption></figure>

### Configuration

* **Import from JSON file** \
  Specifies the path to a JSON file containing context history to import.
* **Context Source**\
  Choose where context is retrieved from:
  * **Translation Memory** \
    Uses recent translations from Translation Memory as context
  * **New Translation**\
    Starts fresh conversation for each translation request
  * **JSON File** \
    Imports context history from the specified JSON file
* **Max Context Entries** \
  Sets the maximum number of context entries to store in memory. Older entries are removed when this limit is reached.

### API Variables

Use the following variable in your API requests to include context memory:

* `$MT::ConversationMemory.Entries::ToArray()`
* `$MT::ContextMemory.Entries::ToArray()`

This variable expands to an array of context entries that can be passed to AI/LLM APIs.

### Example: OpenAI GPT Integration

**Initial prompt:**

```
You will be provided with a sentence in Japanese,
and your task is to translate it into English accurately.
If there are any cultural references or nuances within the text,
kindly provide a brief explanation or context for those as well.
The text is as follows:
```

**System template:**

```json
[{"role": "system", "content": "$PROMPT"}]
```

**User template:**

```json
[{"role": "user", "content": "$ORIGINAL_TEXT"}]
```

**Assistant template:**

```json
[{"role": "assistant", "content": "$TRANSLATED_TEXT"}]
```

**Custom MT Configuration**

Complete configuration example for OpenAI GPT with context memory:

```json
{
  "version": "2",
  "service": "openai",
  "lang": {
    "source": [
      { "name": "Custom", "value": "Custom" },
    ],
    "target": [
      { "name": "Custom", "value": "Custom" },
    ]
  },
  "config": {
    "method": "post",
    "encodeURI": false,
    "encodeURIComponent": false,
    "postURL": "https://api.openai.com/v1/chat/completions",
    "postData": {
      "model": "gpt-3.5-turbo",	  
      "messages": "$MT::ConversationMemory.Entries::ToArray()",	  
      "temperature": 0.9,
      "max_tokens": 4096,
      "top_p": 1,
      "frequency_penalty": 0.7,
      "presence_penalty": 0.7
    },
    "postOptions": {
      "headers": {
        "Authorization": "Bearer [YOUR_API_KEY_HERE]",
        "Content-Type": "application/json"
      }
    },
    "responseParse": true,
    "responseType": "json",
    "responseQuery": "choices[0].message.content"
  }
}
```


# Advanced Settings

Configure advanced translation parameters for fine-tuning request handling, API behavior, and browser automation.

Configure advanced translation parameters for fine-tuning request handling, API behavior, and browser automation.

<figure><img src="/files/LcGl04xBY0SnvGIrMIT2" alt=""><figcaption></figcaption></figure>

## API

Advanced configuration for API-based translation services.

* **Credentials**\
  Enables or disables credentials in API requests for authentication.
* **Timeout (ms)**\
  Sets the maximum wait time for API responses before timing out.
* **Response type**\
  Specifies the expected response format from the API.
* **Response encoding**\
  Sets the character encoding for API responses.
* **Max content length**\
  Maximum size (in bytes) of response content to accept.
* **Max body length**\
  Maximum size (in bytes) of request body to send.

***

## WS & WLM

Configuration for browser-based translation methods that require webpage interaction.

* **Show browser window**\
  Toggles visibility of the browser window during web scraping operations.
  * **Enabled** - Browser window visible (useful for debugging)
  * **Disabled** - Headless mode (recommended for normal use)
* **WS Script** (Web Scraping Script)
* **WLM Script** (Web Language Model Script)
* **Timeout (ms)**\
  Maximum wait time for browser operations before timing out.
* **Evaluation interval (ms)**\
  Frequency of script evaluation checks during browser operations.


# Translation Services

VNTranslator supports various machine translation (MT) and AI/LLM services.

<figure><img src="/files/2T7z21nwcZCuJYsXLGJ1" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** Some translation services are only available in the **Pro version**.
{% endhint %}

## Online Translation Services

### Free Online Services

<table><thead><tr><th width="285.20001220703125">Translation Service</th><th>Notes</th></tr></thead><tbody><tr><td>Google Lite</td><td>Mobile version of Google Translate</td></tr><tr><td>Google Web</td><td>Full-site</td></tr><tr><td>Google Web G2</td><td>Alternative / New Method</td></tr><tr><td>DeepL Web</td><td>Full-site (may not work well)</td></tr><tr><td>DeepL Web G2</td><td>Alternative / New Method</td></tr><tr><td>Bing </td><td>-</td></tr><tr><td>Papago </td><td>-</td></tr><tr><td>Baidu</td><td>-</td></tr><tr><td>Yandex</td><td>-</td></tr><tr><td><del>IBM Watson</del> </td><td>-</td></tr><tr><td>ModernMT</td><td>-</td></tr><tr><td>Reverso</td><td>-</td></tr><tr><td>ChatGPT Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">ChatGPT</a></td></tr><tr><td>Gemini Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">Gemini</a></td></tr><tr><td>Claude Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">Claude</a></td></tr><tr><td>Mistral Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">Mistral</a></td></tr><tr><td>DeepSeek Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">DeepSeek</a></td></tr><tr><td>Grok Web</td><td>Web-based access to <a href="/pages/q3F3xrWhZ70ERkZtWBUd">Grok</a></td></tr></tbody></table>

### API-Based Services (Requires API Key)

<table><thead><tr><th width="285.20001220703125">Translation Service</th><th>Link</th></tr></thead><tbody><tr><td>DeepL API Free</td><td><a href="https://www.deepl.com/en/products/api">https://www.deepl.com/en/products/api</a></td></tr><tr><td>DeepL API Pro</td><td><a href="https://www.deepl.com/en/products/api">https://www.deepl.com/en/products/api</a></td></tr><tr><td>OpenAI API</td><td><a href="https://platform.openai.com/api-keys">https://platform.openai.com/api-keys</a></td></tr><tr><td>OpenAI Translate (legacy)</td><td><a href="https://platform.openai.com/api-keys">https://platform.openai.com/api-keys</a></td></tr><tr><td>OpenAI Conversation (legacy)</td><td><a href="https://platform.openai.com/api-keys">https://platform.openai.com/api-keys</a></td></tr><tr><td>Gemini API</td><td><a href="https://aistudio.google.com/apikey">https://aistudio.google.com/apikey</a></td></tr><tr><td>GeminiAI (legacy)</td><td><a href="https://aistudio.google.com/apikey">https://aistudio.google.com/apikey</a></td></tr><tr><td>Claude API</td><td><a href="https://console.anthropic.com/settings/keys">https://console.anthropic.com/settings/keys</a></td></tr><tr><td>Mistral API</td><td><a href="https://admin.mistral.ai/organization/api-keys">https://admin.mistral.ai/organization/api-keys</a></td></tr><tr><td>DeepSeek API</td><td><a href="https://platform.deepseek.com/api_keys">https://platform.deepseek.com/api_keys</a></td></tr><tr><td>OpenRouter API</td><td><a href="https://openrouter.ai/settings/keys">https://openrouter.ai/settings/keys</a></td></tr></tbody></table>

***

## Offline Translation Services

Translation services that work without an internet connection. Local installation required.

<table><thead><tr><th width="285.2000732421875">Translation Service</th><th>Requirements</th></tr></thead><tbody><tr><td>LM Studio</td><td>Install <a href="/pages/GIJCtNboCaKxWCfJh2JT">LM Studio</a> locally before use</td></tr><tr><td>Google Gemma 3 [LM Studio]</td><td>Install <a href="/pages/GIJCtNboCaKxWCfJh2JT">LM Studio</a> locally before use</td></tr><tr><td>TranslateGemma [LM Studio]</td><td>Install <a href="/pages/GIJCtNboCaKxWCfJh2JT">LM Studio</a> locally before use</td></tr><tr><td>GPT4All</td><td>Install GPT4All locally before use</td></tr><tr><td>LibreTranslate</td><td>Install LibreTranslate locally before use</td></tr></tbody></table>

***

## **Custom** MT

This feature allows customization and integration with third-party machine translation services. Supports advanced methods including web scraping, HTTP GET, and HTTP POST requests.

{% content-ref url="/pages/fL9kcNzjbByGeixa7s5v" %}
[Custom MT](/advanced/custom-mt)
{% endcontent-ref %}

## Troubleshooting

{% content-ref url="/pages/8Nwlooi0sEwXPnZ770Qo" %}
[Machine Translation (MT)](/help/troubleshooting/machine-translation-mt)
{% endcontent-ref %}


# Translation Editor

View, edit, and manage translations in the editor window. The Translation Editor allows you to review source text alongside translations and make manual adjustments as needed.

### Menu Bar

* **Import**\
  Imports translation files to add or update entries in the editor.
* **Export**\
  Exports current translations to a file for backup or external use.
* **Viewing Mode**\
  Switches to read-only mode for reviewing translations without the risk of accidental edits.
* **Editing Mode**\
  Enables full editing capabilities, allowing you to modify translations.

### Floating Menu

Quick access toolbar for common editor actions.

* **Add New Translation**\
  Creates a new translation entry manually.
* **Refresh**\
  Reloads the translation list.
* **Search**\
  Searches through source text and translations to quickly find specific entries.
* **Pagination Up**\
  Navigates to the previous page of translations.
* **Pagination Down**\
  Navigates to the next page of translations.

### Footer Menu

Editor controls located at the bottom of the interface.

* **Zoom Out**\
  Decreases the text size in the editor.
* **Zoom In**\
  Increases the text size in the editor.
* **Layout**\
  Switches between different editor layout options.
* **Show/Hide Floating Menu**\
  Toggles the visibility of the floating menu.
* **Auto Scroll**\
  Automatically scrolls to newly added or updated translations.


# Extra Window

The Extra Window is a separate floating window that displays translations. It can be moved anywhere on the screen, which makes it easy to view translations while playing games or reading visual novels.

**The Extra Window can display one or more of these:**

* **Translated Text** - Text translated into the target language.
* **Original Text** - The source text before translation. (for example, the original Japanese text)
* **JParser** - An extension that converts Japanese text to Hiragana, Katakana, Romaji, or adds Furigana. (reading guides above kanji)
* **Jisho Dictionary** - An extension that shows word definitions and meanings from the Japanese-English dictionary, useful for learning new words.

<figure><img src="/files/VxGWPLx8tF2IwIYHUNTr" alt=""><figcaption></figcaption></figure>

All of these can be shown at once, or just select the ones needed. This makes the Extra Window useful whether for quick translations, comparing original with translated text, reading Japanese characters, or learning new vocabulary.

***

### **Always on Top**

Keeps the Extra Window visible above all other windows.

{% hint style="info" %}
This feature may not work with some games using exclusive fullscreen mode.
{% endhint %}

### **Move to Top (z-index)**

An alternative to "Always on Top" that uses z-index positioning.

### **Text Speed**

Adjusts how quickly text appears in the Extra Window.

<figure><img src="/files/w3QSSHeASnGYBeNlzy1i" alt=""><figcaption></figcaption></figure>

### Click-Through Mode

Allows interaction with content behind the Extra Window while keeping it visible.

{% hint style="info" %}
**Note:** When this mode is enabled, the Extra Window becomes non-interactive. You won't be able to move it, right-click, or perform any direct actions on it.\
To disable this mode, use the local hotkey or go to the Extra Window settings.
{% endhint %}

### **Translation Time**

Shows or hides the translation duration.

### **Background Effect**

Applies visual effects to the Extra Window background. Currently supports Acrylic effect.

{% hint style="info" %}
**Note:** This feature was previously removed due to potential crashes on Windows 11. It is available again starting from version `v0.9.0-beta`.
{% endhint %}

<figure><img src="/files/z7USnSeE8kfTXdkS7vWZ" alt=""><figcaption></figcaption></figure>

### **Window Binding (Experimental)**

Automatically attaches the Extra Window to the game window. The Extra Window follows the game window position in real-time.

### Layout

Customize text layout and display order.

### **Themes**

Choose from available themes to change the appearance of the Extra Window.

***

## Window Settings

### **Frameless**

Removes the title bar for a cleaner look and enables window transparency support.

### Keep Size & Position

Saves and restores the window size and position.

### **Auto Resize**

Automatically adjusts window height based on content.

### **Auto Hide Window**

Automatically hides the Extra Window after displaying the translation.

### Transparent

Enables window transparency.

{% hint style="info" %}
Only works when **Frameless** is enabled
{% endhint %}

### **Taskbar / Focusable**

Toggles whether the Extra Window appears in the taskbar and can be focused.

***

## Advanced Customization

Provides detailed options for customizing text appearance, including direction, color, shadow, stroke, and more.

{% hint style="info" %}
To open Advanced Customization. **Right-click** the text area and select **Advanced Customization.**
{% endhint %}

<figure><img src="/files/NbKqR9RnzpPwQ0LOG4s9" alt=""><figcaption></figcaption></figure>

***

## Local Hotkeys

The Extra Window must be focused to use local hotkeys.

| (↑ / ↓ / ← / →)        | Move window                              |
| ---------------------- | ---------------------------------------- |
| Ctrl + (↑ / ↓ / ← / →) | Resize window                            |
| Ctrl + Alt + ↑         | Move window to top of the screen         |
| Ctrl + Alt + ↓         | Move window to bottom of the screen      |
| Ctrl + Alt + ←         | Resize window width to 50% of screen     |
| Ctrl + Alt + →         | Resize window width to full screen width |
| Alt + M                | Toggle Click-Through Mode                |


# Hyper Overlay

### Translation Boxes (Experimental)

An OCR overlay that detects multiple bounding boxes and instantly translates recognized text.\
Currently supports Fast OCR, Tesseract Server, Windows OCR, and Google Cloud Vision.

<div align="left" data-full-width="false"><figure><img src="/files/Voi2M8Gn99jea8wo4kcB" alt=""><figcaption></figcaption></figure></div>

<div align="left" data-full-width="false"><figure><img src="/files/p5jwsSOIqsYzOHhORLFy" alt=""><figcaption></figcaption></figure></div>


# Local Server

<div align="left"><figure><img src="/files/RXiimXBKoN9k1f5cNkCf" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
This feature is available in **VNTranslator Pro v0.9.2**
{% endhint %}

## Server Configuration

* Server Host: `127.0.0.1` (default)
* Server Port: `7788` (default)

***

## APIs

### Translate

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/translate`

<mark style="color:green;">**`POST`**</mark>  `/api/v1/translate`

<mark style="color:green;">**`POST`**</mark>  `/api/v2/translate`

### TranslationServices

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/services`

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/service/{id}`

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/service/{id}/models`

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/service/{id}/reset`

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/service/{id}/config`

<mark style="color:orange;">**`PUT`**</mark>  `/api/v1/servive/{id}/config`

### TranslationMemories

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/tm/{id}`

<mark style="color:orange;">**`PUT`**</mark>  `/api/v1/tm/{id}`

<mark style="color:red;">**`DELETE`**</mark>  `/api/v1/tm/{id}`

<mark style="color:red;">**`DELETE`**</mark>  `/api/v1/tm/all`

<mark style="color:blue;">**`GET`**</mark>  `/api/v1/tm`

<mark style="color:green;">**`POST`**</mark>  `/api/v1/tm`

<mark style="color:green;">**`POST`**</mark>  `/api/v1/tm/search`


# Hotkeys

### Global Hotkeys

|                                      |                  |
| ------------------------------------ | ---------------- |
| Show or hide the launcher            | Ctrl + Shift + L |
| Show or hide the extra window        | Ctrl + Shift + E |
| Show or hide the smart filtering     | Ctrl + Shift + S |
| Show or hide the translations window | Ctrl + Shift + T |

### Launcher

|                  |               |
| ---------------- | ------------- |
| Relaunch         | Ctrl + R      |
| Reset all config | Ctrl + Delete |

### Extra Window

|                                             |                    |
| ------------------------------------------- | ------------------ |
| Copy text                                   | Ctrl + C           |
| Dark mode                                   | Ctrl + D           |
| Set opacity (0% - 90%)                      | Ctrl + \[0-9]      |
| Set opacity 100%                            | Ctrl + Backspace   |
| Move up                                     | Up                 |
| Move right                                  | Right              |
| Move down                                   | Down               |
| Mode left                                   | Left               |
| Increase height                             | Ctrl + Up          |
| Decrease height                             | Ctrl + Down        |
| Increase width                              | Ctrl + Right       |
| Decrease width                              | Ctrl + Left        |
| Set window to the side top of the screen    | Ctrl + Alt + Up    |
| Set window to the side bottom of the screen | Ctrl + Alt + Down  |
| Set window width 50% of the screen          | Ctrl + Alt + Right |
| Set window width 100% of the screen         | Ctrl + Alt + Left  |

### OCR

|                                  |               |
| -------------------------------- | ------------- |
| Capture                          | Enter / Space |
| Reset position & size to default | Ctrl + Delete |
| Move up                          | Up            |
| Move right                       | Right         |
| Move down                        | Down          |
| Move left                        | Left          |
| Increase height                  | Ctrl + Up     |
| Decrease height                  | Ctrl + Down   |
| Increase width                   | Ctrl + Right  |
| Decrease width                   | Ctrl + Left   |


# Extensions


# JParser

Converting Japanese sentence to Hiragana, Katakana or Romaji

**Features:**

* Convert to: Hiragana, Katakana, Romaji
* Convert mode: Normal, Spaced, Okurigana, Furigana


# Jisho

Japanese-English online dictionary

{% embed url="<https://www.youtube.com/watch?v=qxW5_tyYPp4>" %}

### Data Attribution

The Jisho Extension looks up Japanese words using data from [Jisho.org](https://jisho.org), a free online Japanese-English dictionary.

Jisho.org's dictionary data comes from the [JMdict/EDICT project](http://www.edrdg.org/jmdict/edict.html), maintained by the Electronic Dictionary Research and Development Group (EDRDG), and is licensed under the [Creative Commons Attribution-ShareAlike License](https://www.edrdg.org/edrdg/licence.html).

We thank the Jisho.org team and the EDRDG for making this data freely available.


# GM Lens

Grab any text on the screen and translate it

<figure><img src="/files/ADQeXv7J6jEjOgc6Mqvs" alt=""><figcaption></figcaption></figure>


# Text to Speech

Convert text to spoken audio

<figure><img src="/files/6IjsbThog2C78NOuiZnJ" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The TTS (Text-to-Speech) Extension is available starting from **VNTranslator Pro v1.0.0**, accessible for **Supporter+** tier and above.
{% endhint %}

***

### Enabling the TTS Extension

To enable the TTS Extension, follow these steps:

* Go to **Settings -> Extensions -> Text to Speech**
* Toggle the switch to **On**
* Relaunch the app

***

### Creating a New TTS List

* Open the **TTS Window**
* Click the **New List** button to create a new TTS list

***

### Adding Voices to a TTS List

* Click on the **TTS name** to open the **Voice Editor**
* Click the **Add Voice** button to add a new voice entry
* In the **Character Name** field, enter the character name associated with the voice
* In the **Text Source** field, select the input source for the TTS voice. You can choose between:
  * **Source Text** - Uses the original text as the TTS input
  * **Target Text (Translation)** - Uses the translated text as the TTS input

#### About Character Names

The character name is used to determine which voice will be played based on the text source. Below are the available options:

* **Default** or **None** - Defines the default voice that will be played when no matching character name is found in the source text or translation
* **"%" Pattern (Wildcard)**  - Use the `%` wildcard to define a dynamic name pattern. For example, if the source text contains `Anita: Hello World`, you can enter `Anita%` as the character name to match it
* **Multiple Character Names** - You can enter more than one character name by separating them with a comma (`,`). For example: `Ani%, Amelia%`

***

### Supported TTS Engines

VNTranslator supports the following TTS engines:

#### Online

<figure><img src="/files/AsU88YYozSebFiumjPJf" alt=""><figcaption></figcaption></figure>

* ElevenLabs
  * <https://elevenlabs.io/app/developers>
* Google Cloud TTS
  * <https://docs.cloud.google.com/text-to-speech/docs>
* Speechify
  * <https://console.speechify.ai/>
* Inworld TTS
  * <https://platform.inworld.ai/>

#### Offline

<figure><img src="/files/m7yi8tX2suOp4VLCJPK8" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** Offline TTS engines must be installed on your computer before use.
{% endhint %}

* [Pocket TTS](/features/extensions/text-to-speech/pocket-tts)
* [Kokoro TTS](/features/extensions/text-to-speech/kokoro-tts)
* [VoiceVox (Japanese Only)](/features/extensions/text-to-speech/voicevox)
* ~~Piper TTS~~
* ~~Web Speech API (Browser)~~

***

### Custom Engine

* Endpoint
* ContentType
  * `application/json`
  * `multipart/form-data`
* Headers
* Body
* ResponseType
  * `Audio Format`
  * `Base64 Format`
* ResponseQuery


# Pocket TTS

{% hint style="info" %}
**Pocket TTS** is an offline, CPU-based TTS engine developed by [Kyutai](https://kyutai.org). It supports English only and does not require a GPU to run.
{% endhint %}

### Installation

There are two ways to install Pocket TTS: using **UV** (recommended) or **PIP**.

<details>

<summary><strong>Install via UV (Recommended)</strong></summary>

UV is a fast Python package manager that handles all dependencies automatically in an isolated environment.

**Step 1 - Install UV**

Open **PowerShell** and run the following command:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

For alternative installation methods, refer to the [UV Installation Guide](https://docs.astral.sh/uv/getting-started/installation/).

**Step 2 - Verify the Installation**

After the installation is complete, restart PowerShell and verify that UV is installed correctly by running:

```powershell
uv --version
```

You should see the installed UV version printed in the terminal.

**Step 3 - Run Pocket TTS**

With UV installed, you do not need to install Pocket TTS separately. You can run it directly using the `uvx` command:

```powershell
uvx pocket-tts serve
```

UV will automatically download and install all required dependencies on the first run.

</details>

<details>

<summary><strong>Install via PIP</strong></summary>

If you prefer to install Pocket TTS manually using PIP, follow these steps.

**Step 1 - Install Pocket TTS**

Open a terminal or command prompt and run:

```powershell
pip install pocket-tts
```

**Step 2 - Verify the Installation**

Confirm the installation was successful by running:

```powershell
pocket-tts --version
```

**Step 3 - Run Pocket TTS**

Once installed, start the Pocket TTS server with:

```powershell
pocket-tts serve
```

</details>

***

### Running the Pocket TTS Server

Once the server is running, you can access the web interface at:

```
http://localhost:8000
```

***

### Integrating with VNTranslator

After the Pocket TTS server is running, follow these steps to connect it with VNTranslator:

* Go to **Settings -> Extensions -> Text to Speech**
* Scroll to the **Pocket TTS** settings section
* Enter the **Host** and **Port** of your running Pocket TTS server. By default, these are already set to:
  * **Host:** `http://localhost`
  * **Port:** `8000`

{% hint style="warning" %}
Make sure the Pocket TTS server is running **before** launching a game in VNTranslator. If the server is not running, TTS playback will not work.
{% endhint %}

***

### References

* [Pocket TTS GitHub Repository](https://github.com/kyutai-labs/pocket-tts)
* [Kyutai Blog - Pocket TTS Announcement](https://kyutai.org/blog/2026-01-13-pocket-tts)
* [UV Installation Guide](https://docs.astral.sh/uv/getting-started/installation/)


# Kokoro TTS

{% hint style="info" %}
**Kokoro TTS** is an offline TTS engine based on the [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) model. It supports multiple languages including English, Japanese, and Chinese, and runs on CPU without requiring a GPU.
{% endhint %}

### Installation

There are two ways to install Kokoro TTS: using **UV** (recommended) or **PIP**.

<details>

<summary><strong>Install via UV (Recommended)</strong></summary>

UV is a fast Python package manager that handles all dependencies automatically in an isolated environment.

**Step 1 - Install UV**

Open **PowerShell** and run the following command:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

For alternative installation methods, refer to the [UV Installation Guide](https://docs.astral.sh/uv/getting-started/installation/).

**Step 2 - Verify the Installation**

After the installation is complete, restart PowerShell and verify that UV is installed correctly by running:

```powershell
uv --version
```

You should see the installed UV version printed in the terminal.

**Step 3 - Clone or Download the Repository**

**Clone via Git&#x20;*****(recommended)***

If you have [Git](https://git-scm.com/downloads) installed, open PowerShell and run:

```powershell
git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI
```

**Download as ZIP**

If you do not have Git installed, you can download the repository manually:

1. Go to <https://github.com/remsky/Kokoro-FastAPI>
2. Click the **Code** button, then select **Download ZIP**
3. Extract the downloaded ZIP file to a folder of your choice
4. Open PowerShell, navigate to the extracted folder:

```powershell
cd path\to\Kokoro-FastAPI
```

**Step 4 - Run Kokoro TTS**

Start the Kokoro TTS server using the provided startup script for CPU:

```powershell
.\start-cpu.ps1
```

UV will automatically install all required dependencies on the first run.

</details>

<details>

<summary><strong>Install via PIP</strong></summary>

If you prefer to install Kokoro TTS manually using PIP, follow these steps.

**Step 1 - Clone or Download the Repository**

**Clone via Git&#x20;*****(recommended)***

```powershell
git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI
```

**Download as ZIP**

If you do not have Git installed, you can download the repository manually:

1. Go to <https://github.com/remsky/Kokoro-FastAPI>
2. Click the **Code** button, then select **Download ZIP**
3. Extract the downloaded ZIP file to a folder of your choice
4. Open PowerShell, navigate to the extracted folder:

```powershell
cd path\to\Kokoro-FastAPI
```

**Step 2 - Install Dependencies**

Install the required Python packages using PIP:

```powershell
pip install -r requirements.txt
```

**Step 3 - Run Kokoro TTS**

Once the dependencies are installed, start the Kokoro TTS server:

```powershell
python -m uvicorn api.src.main:app --host 0.0.0.0 --port 8880
```

</details>

***

### Running the Kokoro TTS Server

Once the server is running, you can access the web interface at:

```
http://localhost:8880/web
```

The API documentation is also available at:

```
http://localhost:8880/docs
```

***

### Integrating with VNTranslator

After the Kokoro TTS server is running, follow these steps to connect it with VNTranslator:

* Go to **Settings -> Extensions -> Text to Speech**
* Scroll to the **Kokoro TTS** settings section
* Enter the **Host** and **Port** of your running Kokoro TTS server. By default, these are already set to:
  * **Host:** `http://localhost`
  * **Port:** `8880`

{% hint style="warning" %}
Make sure the Kokoro TTS server is running **before** launching a game in VNTranslator. If the server is not running, TTS playback will not work.
{% endhint %}

***

### References

* [Kokoro FastAPI GitHub Repository](https://github.com/remsky/Kokoro-FastAPI)
* [Kokoro-82M Model on Hugging Face](https://huggingface.co/hexgrad/Kokoro-82M)
* [UV Installation Guide](https://docs.astral.sh/uv/getting-started/installation/)


# VoiceVox

{% hint style="info" %}
**VoiceVox** is an offline TTS engine developed for Japanese speech synthesis. It supports a wide range of voice characters and runs on CPU without requiring a GPU.
{% endhint %}

### Installation

This guide uses **VoiceVox Engine version 0.25.1**. Steps may differ slightly for other versions.

**Step 1 - Download VoiceVox Engine**

* Go to the VoiceVox Engine releases page:\
  <https://github.com/VOICEVOX/voicevox_engine/releases>
* Find version **0.25.1** and download the **Windows (CPU版)** file

**Step 2 -** Extract the Downloaded File

Once the download is complete, extract the downloaded file to a folder of your choice.

The extracted folder structure will look like this:

```
voicevox_engine-windows-cpu-0.25.1\
└── windows-cpu\
    ├── run.exe
    ├── resources\
    └── ...
```

**Step 3 - Run VoiceVox**&#x20;

To start VoiceVox, navigate to the `windows-cpu` folder and **double-click** `run.exe`.

```
voicevox_engine-windows-cpu-0.25.1\windows-cpu\run.exe
```

***

### Integrating with VNTranslator

After VoiceVox server is running, follow these steps to connect it with VNTranslator:

* Go to **Settings -> Extensions -> Text to Speech**
* Scroll to the **VoiceVox** settings section
* Enter the **Host** and **Port** of your running VoiceVox server. By default, these are already set to:
  * **Host:** `http://localhost`
  * **Port:** `50021`
* Enter the **Resource Path** - The path to the `resources` folder inside your extracted VoiceVox Engine folder. For example: \
  `path\to\voicevox_engine-windows-cpu-0.25.1\windows-cpu\resources`

{% hint style="info" %}
The **Resource Path** is used to display voice character avatars and play audio samples directly within VNTranslator. If left empty, avatars and audio previews will not be available.
{% endhint %}

{% hint style="warning" %}
Make sure the VoiceVox server is running **before** launching a game in VNTranslator. If the server is not running, TTS playback will not work.
{% endhint %}

***

### References

* [VoiceVox Engine GitHub Releases](https://github.com/VOICEVOX/voicevox_engine/releases)
* [VoiceVox Official Website](https://voicevox.hiroshiba.jp/)


# Clipboard

The Clipboard feature automatically translates any text copied to the clipboard.

## How to Translate Any Text with Clipboard

The Clipboard feature automatically translates any text copied to your clipboard, in real time - not just from games, but from any application on your computer.

***

### How It Works

When you copy text to your clipboard from any source, VNTranslator automatically detects it and displays the translation in the Extra Window. This works with any application on your computer, without needing to switch windows or paste anything manually.

***

### What You Can Translate

The Clipboard Translator works with:

* Visual novels and games that have a "Copy Text to Clipboard" feature
* Third-party applications or game mods that support clipboard copying
* Text from websites in any web browser
* Chat applications and messaging platforms
* Documents and text files from any program
* Any other application that supports text selection and copying

***

### Getting Started

<figure><img src="/files/vEKw613kz9YDDR1FnoFj" alt=""><figcaption></figcaption></figure>

1. Select **Clipboard** from the module list
2. Select **Extra Window** from the output list
3. Click the **Start** button

***

### Integration with Games

Many visual novels and PC games include a built-in clipboard copy feature. When playing these games, simply use their copy function, and VNTranslator will translate the text automatically without any additional setup.

Ren'Py games in particular have two dedicated Clipboard-based methods - the RenPy Clipboard Plugin and Clipboard Voicing - covered in detail in the [Ren'Py Games guide](/user-guide/renpy-games).

***

### FAQ: Translating Text with Clipboard

<details>

<summary><strong>What is the Clipboard feature in VNTranslator?</strong></summary>

Clipboard is a VNTranslator module that automatically translates any text copied to your clipboard and displays the result in the Extra Window, in real time. It works across any application on your computer, not just games.

</details>

<details>

<summary><strong>Does Clipboard translation only work with games?</strong></summary>

No. While it's commonly used with visual novels and PC games that support clipboard copying, Clipboard translation works with any application that lets you copy text, including web browsers, chat apps, documents, and text files.

</details>

<details>

<summary><strong>Where does the translated text appear?</strong></summary>

Translated text appears in the [Extra Window](/features/extra-window), which needs to be selected as the output when starting the Clipboard module.

</details>

<details>

<summary><strong>Why isn't my copied text being translated?</strong></summary>

Check that both **Clipboard** is selected from the module list and **Extra Window** is selected from the output list before clicking Start. If translation still doesn't appear, confirm the source application actually copies text to the clipboard when you use its copy function.

</details>

<details>

<summary><strong>What's the difference between Clipboard and OCR?</strong></summary>

Clipboard translation reads text that's been copied to the clipboard, either manually or through an application's built-in copy feature. OCR instead captures text directly from the screen, which makes it useful for games or applications that don't support clipboard copying.

</details>


# OCR

Visual Novel OCR & Text Recognition for Video Games. Real-Time Screen OCR Translator.

## How to Translate Games with OCR

The OCR feature extracts and translates text directly from your screen in real time using Optical Character Recognition (OCR). It's ideal for visual novels and games that don't support clipboard or text extraction. It can translate dialogue from virtually any game or application.

{% embed url="<https://www.youtube.com/watch?v=AAhya7IPYZ0>" %}

### How OCR Works

OCR works by capturing a selected area of your screen, recognizing the text using an OCR engine, and then translating it in real time. You can display the translation results in two ways: using **Extra Window** or **Hyper Overlay**.

***

### Output Methods

Before you start, it's important to understand the two available output methods so you can choose the one that best fits your setup.

#### Extra Window

<figure><img src="/files/8CEdMRee7h0s8Nq3ZjV3" alt=""><figcaption></figcaption></figure>

The recognized text and translation are displayed in a **separate floating window**.

* A dedicated window shows both the original recognized text and the translation
* The window can be repositioned anywhere on your screen
* Best suited for **multi-monitor setups** or when you prefer a separate panel

#### Hyper Overlay

<figure><img src="/files/cwns79PKcEvIDWOLULvw" alt=""><figcaption></figcaption></figure>

The translation is displayed **directly over the original text** on your game screen.

* Translation appears on top of the recognized text, right on the game screen
* Provides a clean, immersive reading experience
* No additional floating windows to manage
* Best suited for **single-screen setups** and **fullscreen games**

***

### Getting Started

{% stepper %}
{% step %}

#### Install an OCR Engine

Before you can use OCR, you need to install at least one supported OCR engine.

{% hint style="info" %}
Recommended for most users:

* **Fast OCR** - A lightweight and accurate offline OCR engine without extra setup.
* **Google Cloud Vision** - Best accuracy for complex backgrounds and colored text. Requires an internet connection and API key.
* **ScreenAI OCR** - A modern offline engine that handles moderate background noise and multi-colored.
* **Nanonets OCR Small** *(via LM Studio)* - A high-performance AI-based engine for offline use. Requires at least 8 GB of VRAM.
  {% endhint %}

For a full list of supported engines and installation instructions, see [OCR Engines](/user-guide/ocr/ocr-engines).
{% endstep %}

{% step %}

#### Configure and Start OCR

<figure><img src="/files/vxK0pcptH69Hcfz5bODc" alt=""><figcaption></figcaption></figure>

1. Select **OCR** from the module list
2. Select an **OCR Engine**
3. Select your preferred **Output Method**:
   * Choose **Hyper Overlay** for an immersive, in-place translation experience
   * Choose **Extra Window** if you prefer a separate translation panel
4. Click the **Start** button

{% hint style="info" %}
If you're using **Windows OCR** or **Tesseract OCR**, you'll also need to select the appropriate **Language** for that engine.
{% endhint %}
{% endstep %}

{% step %}

#### Position the Capture Area

<figure><img src="/files/8cxYWoimeUZoahc8nvZi" alt=""><figcaption></figcaption></figure>

After starting OCR, a transparent **Capture Area** window will appear on your screen.

* Drag and resize the Capture Area to cover the **dialogue text box** in your game
* Make sure it covers only the text area - avoid capturing UI buttons, character sprites, or background elements

For more details, see [Interface Overview](https://docs.vntranslator.com/user-guide/ocr/interface-overview).
{% endstep %}

{% step %}

#### Start Capturing

Once the Capture Area is positioned, click the **Capture** button in the Side Toolbar (or press **Space**) to trigger a single capture and confirm the text is recognized and translated correctly.

Once you've confirmed it works, enable **Auto Capture** (or press **Ctrl + Shift + A**) to capture and translate continuously while you play, without needing to trigger it manually for every line.

For a full breakdown of Capture, Smart Capture, and Auto Capture options, see [Interface Overview](/user-guide/ocr/interface-overview).\
If screen capture fails or shows an error, refer to [Troubleshooting](/help/troubleshooting/ocr).
{% endstep %}
{% endstepper %}

***

### Tips for Better Results

* **Position the capture area** over the text dialogue box in your game
* **Choose a modern engine** like Fast OCR or ScreenAI OCR for strong accuracy with minimal setup
* **Use Pre-processing** only if you're using an older, traditional-style OCR engine that needs help with contrast or background noise
* **Use Post-processing** (RegExp) to correct common OCR errors or remove unwanted characters
* **Try different OCR engines** to find the best match for your specific game or visual novel

***

### FAQ: Translating Games with OCR

<details>

<summary><strong>What is OCR translation, and when should I use it instead of other methods?</strong></summary>

VNTranslator offers several ways to translate a game depending on what it supports, including AutoTrans, Clipboard, XUAT, and TextractorCLI. OCR is the option that doesn't depend on the game supporting any of these, since it reads text directly from the screen. This makes it useful for games or applications where the other methods aren't available.

</details>

<details>

<summary><strong>What's the difference between Extra Window and Hyper Overlay?</strong></summary>

Extra Window displays the recognized text and translation in a separate floating panel, which works well for multi-monitor setups. Hyper Overlay displays the translation directly on top of the original text on your game screen, which suits single-screen and fullscreen setups.

</details>

<details>

<summary><strong>Which OCR engine should I use?</strong></summary>

It depends on your setup: Fast OCR and ScreenAI OCR are modern offline engines that work well for most games, Google Cloud Vision offers strong accuracy for complex text, and Nanonets OCR Small works fully offline if you have enough VRAM. See [OCR Engines](/user-guide/ocr/ocr-engines) for a full comparison of all supported engines.

</details>

<details>

<summary><strong>Why isn't OCR detecting any text on my screen?</strong></summary>

Check that the Capture Area is positioned directly over the dialogue text box, that it doesn't include UI buttons, sprites, or background elements, and that **Capture** or **Auto Capture** has actually been triggered. If you're using an older, traditional-style engine, try enabling Pre-processing and adjusting the Threshold value - see [Pre-processing](/user-guide/ocr/pre-processing) for details.

</details>

<details>

<summary><strong>How do I fix incorrect or garbled OCR text?</strong></summary>

Use Post-processing (RegExp) to filter out recurring recognition errors or unwanted characters before translation. See [Post-processing](/user-guide/ocr/post-processing) and [Understanding OCR & Improving Accuracy](/user-guide/ocr/understanding-ocr-and-improving-accuracy) for detailed tips.

</details>

<details>

<summary><strong>Does OCR work with any game or application?</strong></summary>

OCR captures whatever is visible on your screen, so it can work with most games and applications regardless of engine. Accuracy still depends on the OCR engine used and factors like font style, background complexity, and text size.

</details>

***

### OCR Documentation Index

<table><thead><tr><th width="259.20001220703125" valign="top">Page</th><th>Description</th></tr></thead><tbody><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/interface-overview">Interface Overview</a></td><td>Learn about the OCR interface components: Capture Area, Side Toolbar, and Status Bar</td></tr><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/ocr-engines">OCR Engines</a></td><td>Compare all supported OCR engines and find the best one for your game</td></tr><tr><td valign="top"><a href="/pages/K5fjV6gumH3VRN7LymXl">OCR Settings</a></td><td>Configure Auto Capture interval, Clipboard copy, Recording Mode, and other OCR options</td></tr><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/ocr-master">OCR Master</a></td><td>Advanced OCR controls available in the Pro version</td></tr><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/pre-processing">Pre-processing</a></td><td>Improve image quality before OCR processing</td></tr><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/post-processing">Post-processing</a></td><td>Refine OCR output using Regular Expressions</td></tr><tr><td valign="top"><a href="https://docs.vntranslator.com/user-guide/ocr/understanding-ocr-and-improving-accuracy">Understanding OCR &#x26; Improving Accuracy</a></td><td>In-depth guide on how OCR works and how to improve recognition accuracy</td></tr></tbody></table>

**Having trouble?** See the [Troubleshooting](https://docs.vntranslator.com/help/troubleshooting/ocr) section for common issues and solutions.


# Interface Overview

OCR interface components and how to use them for capturing and translating text from your game screen.

Learn about the OCR interface components and how to use them for capturing and translating text from your game screen.

The OCR interface layout depends on the **output method** you selected when starting OCR:

* **Extra Window** - The interface shows the **Capture Area** and the **Side Toolbar** (right side)
* **Hyper Overlay** - The interface shows the **Overlay Toolbar** (left side), the **Capture Area**, and the **Side Toolbar** (right side)

<figure><img src="/files/8cxYWoimeUZoahc8nvZi" alt=""><figcaption></figcaption></figure>

## Capture Area

The Capture Area is a transparent overlay window that defines which part of your screen will be captured for OCR text recognition.

**How to Use:**

* Position the Capture Area over the dialogue text box in your game
* Resize the window to fully cover the text area
* Make sure the Capture Area includes only the text - avoid capturing UI buttons, character sprites, or background elements
* Once positioned, the Capture Area will automatically detect and capture text when **Auto Capture** is enabled

**Tips:**

* Leave a small margin around the text to ensure all characters are captured correctly
* Avoid capturing unnecessary parts of the screen, as this can reduce OCR accuracy

***

## Overlay Toolbar

{% hint style="info" %}
The Overlay Toolbar is only available when using **Hyper Overlay** as the output method. It will not appear when using Extra Window.
{% endhint %}

The Overlay Toolbar appears on the **left side** of the Capture Area and provides controls for managing how the translated text is displayed directly on your game screen.

#### **Hyper Overlay Toggle**

Turns Hyper Overlay on or off without stopping the OCR session.

#### **Text Styles**

<figure><img src="/files/8YRIpkOdHXtJifYOpiBH" alt=""><figcaption></figcaption></figure>

* **Auto Text Size:** Automatically adjusts the text size to fit within the recognized text area
* **Auto Text Color (B/W):** Automatically sets the text color to black or white based on the background for better readability
* T**ext Size:** Manually sets the text size. Only available when **Auto Text Size** is disabled
* **Min. Text Size:** Sets the minimum text size limit when **Auto Text Size** is enabled
* **Max. Text Size:** Sets the maximum text size limit when **Auto Text Size** is enabled
* **Font:** Sets the font used for the displayed translation text
* **Text Color:** Manually sets the text color. Only available when **Auto Text Color** is disabled

#### **Background**

Controls the background displayed behind the translated text on screen.

* **None:** No background
* **Default:** Applies a blur effect and removes the original text from the background for a cleaner overlay
* **Solid:** Displays a solid color background behind the translated text. You can adjust the color and opacity

#### Text Segmention (N/A)

...

#### **Clear All Text**

Removes all translated text currently displayed on the Hyper Overlay.\
This does not stop OCR - it only clears the overlay text that is currently visible on screen.

***

## Side Toolbar

The Side Toolbar appears on the **right side** of the Capture Area and provides quick access to OCR controls and settings.

#### Capture

Manually triggers a screen capture and sends it to the OCR engine for text recognition.

* Hotkey: **Ctrl + Space** (default)

#### Smart Capture (right-click the Capture button to access settings)

<figure><img src="/files/30BOJrLi6Wy3oqM1ASUZ" alt=""><figcaption></figcaption></figure>

Smart Capture adds intelligent detection before triggering OCR, helping to reduce unnecessary captures and improve accuracy.

* **Change Detection** - Only triggers a capture when the screen content has changed significantly:
  * **Min. Threshold (%):** Minimum percentage of screen change required to trigger a capture
  * **Max. Threshold (%):** Maximum percentage of screen change allowed before a capture is triggered
* **Stability Detection** - Waits until the screen content has been stable before triggering a capture:
  * **Min. Stable Duration (ms):** Minimum time (in milliseconds) the screen must remain unchanged before a capture is triggered
  * **Max. Wait Time (ms):** Maximum time (in milliseconds) to wait for the screen to stabilize before forcing a capture

#### Auto Capture

Automatically captures and processes text at regular intervals.

* Continuously monitors the Capture Area for new or changed text
* Hotkey: **Ctrl + Shift + A** (default)

#### Pre-processing

Opens image enhancement settings that are applied to the captured image before it is sent to the OCR engine.

* Adjust settings such as brightness, contrast, threshold, and filters
* Helps improve OCR accuracy, especially when using traditional OCR engines (Tesseract OCR, Windows OCR)

For more details, see [Pre-processing](https://docs.vntranslator.com/user-guide/ocr/pre-processing)

#### OCR Engine

Opens the OCR engine selection panel, allowing you to switch to a different OCR engine or language without restarting.

For a full list of available engines, see [OCR Engines](https://docs.vntranslator.com/user-guide/ocr/ocr-engines)

#### Capture Area / Screen Capture (Mouse Click-Through)

Toggles whether mouse clicks pass through the Capture Area window to the game beneath it.

* **ON** (default) - The Capture Area works normally and can be moved and resized using the mouse
* **OFF** - The Capture Area is locked in place and cannot be moved. Mouse clicks pass through to the game window, allowing you to interact with your game normally

#### Set Region

Allows you to redefine the Capture Area by drawing a new region directly on the screen.

* Hotkey: **Ctrl + Shift + R** (default)

***

## Status Bar

The Status Bar is displayed at the bottom of the Capture Area window and shows real-time information about the current OCR session.

**Information displayed:**

* Current Display Settings
* Capture Area Coordinates
* OCR Processing Status


# OCR Engines

| OCR Engine                                                                                                   | Best For                                           | Notes                                                                                               |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [**Google Cloud Vision**](/user-guide/ocr/ocr-engines/google-cloud-vision)                                   | <p>Complex background,<br>rotated/colored text</p> | <ul><li>⭐⭐⭐⭐⭐</li><li>🌐 Online</li><li>Cloud-based AI</li><li>Paid (Free tier available)</li></ul> |
| [**Azure Cloud Vision**](/user-guide/ocr/ocr-engines/azure-cloud-vision)                                     | <p>Complex background,<br>rotated/colored text</p> | <ul><li>⭐⭐⭐⭐</li><li>🌐 Online</li><li>Cloud-based AI</li><li>Paid (Free tier available)</li></ul>  |
| [Nanonets OCR small ](/user-guide/ocr/ocr-engines/nanonets-ocr-small)                                        | Complex background, rotated/colored text           | <ul><li>⭐⭐⭐🌠</li><li>Offline - Custom</li><li>AI-based (LLM)</li></ul>                             |
| [Fast OCR](/user-guide/ocr/ocr-engines/fast-ocr)                                                             | Moderate background noise, multi-color text        | <ul><li>⭐⭐⭐</li><li>Offline</li><li>Modern OCR Engine</li></ul>                                     |
| [ScreenAI OCR](/user-guide/ocr/ocr-engines/screenai-ocr)                                                     | Moderate background noise, multi-color text        | <p></p><ul><li>⭐⭐⭐</li><li>Offline</li><li>Modern OCR Engine</li></ul>                              |
| Qwen 2.5 VL 7B                                                                                               | Complex background, rotated/colored text           | <ul><li>⭐⭐⭐</li><li>Offline - Custom</li><li>AI-based (LLM)</li></ul>                               |
| [Gemma 3 Vision](/user-guide/ocr/ocr-engines/gemma-3-4b-vision)                                              | Complex background, rotated/colored text           | <ul><li>⭐⭐⭐</li><li>Offline - Custom</li><li>AI-based (LLM)</li></ul>                               |
| EasyOCR                                                                                                      | Moderate background noise, multi-color text        | <ul><li>⭐⭐</li><li>Offline - Custom</li><li>Modern ML-based</li></ul>                               |
| [**Tesseract OCR**](/user-guide/ocr/ocr-engines/tesseract-ocr)                                               | Basic black text on white background               | <ul><li>⭐</li><li>Offline</li><li>Traditional OCR engine</li></ul>                                  |
| [**Windows OCR**](/user-guide/ocr/ocr-engines/windows-ocr)                                                   | Basic black text on white background               | <ul><li>⭐</li><li>Offline</li><li>Traditional OCR engine</li></ul>                                  |
| ~~**Google Lens**~~                                                                                          | <p>Complex background,<br>rotated/colored text</p> | <ul><li>⭐⭐⭐⭐</li><li>🌐 Online</li><li>Cloud-based AI</li><li>Unstable</li></ul>                    |
| <p><a href="/pages/IxLIxTyeCEhhwEdd3AZf"><strong>Custom -</strong> <br><strong>Command Line</strong></a></p> | Custom workflows and integration                   | <ul><li>Requires setup knowledge</li><li>Highly flexible for developers</li></ul>                   |
| <p><a href="/pages/U8HsrSSYHOwJhkqMSNlA"><strong>Custom -</strong> <br><strong>HTTP POST</strong></a></p>    | Custom workflows and integration                   | <p></p><ul><li>Requires setup knowledge</li><li>Highly flexible for developers</li></ul>            |


# OCR Engine Installer

{% hint style="info" %}
This installer has been tested and works well on Windows 11. If the installation does not work, the best approach is to manually install the OCR engine.
{% endhint %}

Simply select the OCR engine you want to install.\
For Tesseract OCR and Windows OCR, the installation includes English, Chinese, Japanese, and Korean languages.

<figure><img src="/files/q2QeM09DYLwDHZeUP3nN" alt=""><figcaption></figcaption></figure>

## How to Get Started:

* Download the **VNTOCR\_Installer.exe** from <https://fazx.itch.io/vntocr-installer>
* Run **VNTOCR\_Installer.exe** as Administrator
* Select the OCR Engine:
  * For example, to install Tesseract OCR, press **1** and then **Enter**
* Press **Y** to confirm the installation
* Wait for the installation process to complete

Once the installation is finished, you can start using VNTranslator OCR with the selected engine.


# Google Cloud Vision

## Get started

You need to connect your Google Account to your Google Cloud Vision project

### **Step 1: Create a Google Cloud Account**

* Visit the [Google Cloud Platform](https://cloud.google.com/)
* Click **Get Started for Free**
* Follow the instructions to create an account:
  * Provide basic details like your email address and billing information
  * Note: Google Cloud provides $300 in free credit for new users, valid for the first 90 days
* After signing up, you will be redirected to the Google Cloud Console

### **Step 2: Create a New Project**

* In the Console, click the **Project Selector** at the top of the page
* Click **New Project** and provide a name for your project
* Select the project and ensure it’s active

### **Step 3: Enable the Google Cloud Vision API**

<figure><img src="/files/P3tDO4ZFnTeEaJCuruM2" alt=""><figcaption></figcaption></figure>

* In the Google Cloud Console:
  * Navigate to the **Navigation Menu** (☰) in the upper left corner
  * Click **APIs & Services -> Library**
* In the API Library, search for **Cloud Vision API**&#x20;
  * <https://console.cloud.google.com/apis/library/vision.googleapis.com>
* Click the **Cloud Vision API** option and then click **Enable**

### **Step 4: Generate an API Key**

<figure><img src="/files/hSJnoZmgnundiCwbI5Xf" alt=""><figcaption></figcaption></figure>

* Navigate to **APIs & Services -> Credentials**.
* Click **+ Create Credentials** and select **API Key**
* An API Key will be generated
  * This key will be needed to integrate with VNTranslator

### **Step 5: Integrate with VNTranslator**

* Go to **Settings -> Modules -> OCR -> Google API Key**
* Paste the API Key you generated in Step 4 into the **Google API Key** field


# Azure Cloud Vision

## Get started

### **Step 1: Create an Azure Account**

* Visit the [Azure Cloud](https://azure.microsoft.com/free/)
* Click **Try Azure for free**
* Follow the instructions to create account:
  * Provide basic details like your email address and billing information
  * New users receive **$200 in free credit** for the first 30 days.
* After signing up, you will be redirected to the Azure Portal

### **Step 2: Create a** Computer Vision **Resource**

<figure><img src="/files/VbY9sNbikYNjfUIdYsST" alt=""><figcaption></figcaption></figure>

* In the [Azure Portal](https://portal.azure.com/):
  * Click **Create a resource** in the left-hand menu
  * Search for **Computer Vision** in the search bar
* Select **Computer Vision** and click **Create**
* Fill in the required details:
  * **Subscription**: Choose your Azure subscription
  * **Resource Group**: Create a new one or use an existing group
  * **Region**: Choose the region closest to your location
  * **Name**: Give your resource a unique name
  * **Pricing Tier**: Select **Free** or another available tier based on your needs
* Click **Review + Create**, then **Create**

### **Step 3: Your API Key and Endpoint**

<figure><img src="/files/Nuy4p84HkY7AgiV9N0NG" alt=""><figcaption></figcaption></figure>

* Navigate to your **Computer Vision** resource in the Azure Portal
* Click **Keys and Endpoint** from the left-hand menu
* Copy the **API Key** and **Endpoint** for use in VNTranslator

### **Step 5: Integrate with VNTranslator** <a href="#step-5-integrate-with-vntranslator" id="step-5-integrate-with-vntranslator"></a>

* Go to **Settings -> Modules -> OCR**
* Paste the **API Key 1 or API Key 2** from Step 3 into the **Azure API Key** field
* Configure the **Azure Request URL** as follows:
  * URL Format: \
    https\://{endpoint}/vision/v3.2/ocr\[?language]\[\&detectOrientation]\[\&model-version]
  * Replace **{endpoint}** with your Computer Vision Resource Endpoint. For example:\
    <https://vntranslator.cognitiveservices.azure.com/vision/v3.2/ocr?language=ja\\&model=2022-04-30>

### Request parameters

```
https://{endpoint}/vision/v3.2/ocr[?language][&detectOrientation][&model-version]
```

* **language (optional)**\
  The BCP-47 language code of the text to be detected in the image.The default value is "unk", then the service will auto detect the language of the text in the image.
* **detectOrientation (optional)**\
  Whether detect the text orientation in the image. With detectOrientation=true the OCR service tries to detect the image orientation and correct it before further processing (e.g. if it's upside-down).
* **model-version (optional)** \
  Optional parameter to specify the version of the AI model. The default value is "latest".


# Fast OCR

{% hint style="info" %}
This OCR engine is available in the Pro version.
{% endhint %}


# ScreenAI OCR

### **Overview**

ScreenAI is an offline OCR engine that runs fast on CPU-only, with solid text recognition and support for many languages. It is a portable, standalone executable.

* Download the ScreenAI OCR from: <https://fazx.itch.io/vntranslator-plugins>
* Source Code: <https://gist.github.com/garudamods/3dd3452c36d8513584490b535bd3e901>
* On first run, `ScreenAI.exe` will automatically download the required Screen AI package.

There are three ways to integrate ScreenAI with VNTranslator's OCR module.

***

### Method 1 - HTTP POST (Custom Engine)

Run `ScreenAI.exe` first, then add it as a Custom Engine in VNTranslator with the following configuration:

```json
URL: http://localhost:62815/ocr
Content-Type: application/json
Headers: {}
Body: {"image":"$IMAGE_BASE64", "type": "base64"}
Response Type: JSON
Response Query: fullText
```

### **Method 2 - Command Line (Custom Engine)**

Add ScreenAI as a Custom Engine using the command line method:

```powershell
"x:\path\to\ScreenAI.exe" "$IMAGE_PATH"
```

### Method 3 - ScreenAI OCR Path

* Download the ScreenAI portable executable.
* Place `ScreenAI.exe` in a folder of your choice.
* Open VNTranslator and go to **Settings -> Modules -> OCR -> ScreenAI OCR path**.
* Enter the full path to your `ScreenAI.exe` file.\
  Example: X`:\OCR\ScreenAI.exe`
* then select **ScreenAI OCR** as your OCR engine.


# Nanonets OCR small

### Model

* <https://huggingface.co/nanonets/Nanonets-OCR-s>
* <https://huggingface.co/unsloth/Nanonets-OCR-s-GGUF>

### Custom - HTTP POST

**URL:**&#x20;

* `http://127.0.0.1:1234/v1/chat/completions`

**Content Type:**&#x20;

* `application/json`

**Headers:**&#x20;

* `{}`

**Body:**

{% code overflow="wrap" %}

```json
{
  "model": "nanonets-ocr-s",
  "messages": [
    {
      "role": "system", "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [        
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,$IMAGE_BASE64"
          }
        },
        { 
          "type": "text", 
          "text": "Extract the text from the image above as if you were reading it naturally. Return only valid words and complete sentences."
        }
      ]
    }
  ],
  "stream": false
}
```

{% endcode %}

**Response Type:**

* `JSON`

**Response Query:**

* `choices[0].message.content`


# Gemma 3 4b Vision

### Model

* <https://huggingface.co/google/gemma-3-4b-it>
* <https://huggingface.co/lmstudio-community/gemma-3-4b-it-GGUF>

### Custom - HTTP POST

URL:&#x20;

* `http://127.0.0.1:1234/v1/chat/completions`

Content Type:&#x20;

* `application/json`

Headers:&#x20;

* `{}`

Body:

{% code overflow="wrap" %}

```json
{
  "model": "nanonets-ocr-s",
  "messages": [
    {
      "role": "system", "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [        
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,$IMAGE_BASE64"
          }
        },
        { 
          "type": "text", 
          "text": "Extract the text from the image above as if you were reading it naturally. Return only valid words and complete sentences."
        }
      ]
    }
  ],
  "stream": false
}
```

{% endcode %}

Response Type:

* `JSON`

Response Query:

* `choices[0].message.content`


# Windows OCR

### Supported languages

{% hint style="info" %}
The default language used will be based on your Windows system language (OCR language packs are available for install).

If you are using **Windows OCR** or **Tesseract OCR**, make sure to select the correct OCR language for your game.

**For Japanese games:**

* Windows OCR: `Japanese`
* Tesseract OCR: `Japanese (jpn.traineddata)`

**For English games:**

* Windows OCR: `English (United States)` or `English (United Kingdom)`
* Tesseract OCR: `English (eng.traineddata)`
  {% endhint %}

Windows OCR can only recognize languages that have the OCR language pack installed

The list can be obtained via **PowerShell** by running the following commands:

```
[Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
```

```
[Windows.Media.Ocr.OcrEngine]::AvailableRecognizerLanguages
```

### How to query for OCR language packs <a href="#how-to-query-for-ocr-language-packs" id="how-to-query-for-ocr-language-packs"></a>

To return the list of support language packs, open **PowerShell** as an Administrator (right-click, then select "Run as Administrator"), and enter the following command:

```
Get-WindowsCapability -Online | Where-Object { $_.Name -Like 'Language.OCR*' }
```

An example output:

```
Name  : Language.OCR~~~en-GB~0.0.1.0
State : NotPresent

Name  : Language.OCR~~~en-US~0.0.1.0
State : Installed

Name  : Language.OCR~~~ja-JP~0.0.1.0
State : NotPresent
```

{% hint style="info" %}
The language and location is abbreviated, so "en-US" would be "English-United States" and "en-GB" would be "English-Great Britain". If a language is not available in the output, then it's not supported by OCR.
{% endhint %}

### How to install an OCR language pack <a href="#how-to-install-an-ocr-language-pack" id="how-to-install-an-ocr-language-pack"></a>

The following commands install the OCR pack for "ja-JP":

```
$Capability = Get-WindowsCapability -Online | Where-Object { $_.Name -Like 'Language.OCR~~~ja-JP~0.0.1.0' }
```

```
$Capability | Add-WindowsCapability -Online
```


# Tesseract OCR

{% embed url="<https://www.youtube.com/watch?v=5Uzl211TxjY>" %}

### **Download & Install Tesseract**

* Visit the [Tesseract at UB Mannheim](https://github.com/UB-Mannheim/tesseract/wiki)
* Select the **tesseract-ocr-w64-setup-v5.3.x.exe (64 bit**) file to download the Tesseract executable installer
* Once downloaded, open the executable file and follow the installation prompts

{% hint style="info" %}
Make sure you have installed the tesseract-64bit in C:\Program Files\Tesseract-OCR.

If you are using **Windows OCR** or **Tesseract OCR**, make sure to select the correct OCR language for your game.

**For Japanese games:**

* Windows OCR: `Japanese`
* Tesseract OCR: `Japanese (jpn.traineddata)`

**For English games:**

* Windows OCR: `English (United States)` or `English (United Kingdom)`
* Tesseract OCR: `English (eng.traineddata)`
  {% endhint %}

### Trained Data Files (Languages)

You can download the `.traineddata` file for the language you need and place it in Tesseract OCR installation directory `C:\Program Files\Tesseract-OCR\tessdata`\\`[here]` \
(this should be the same as where the tessdata directory is installed)

> **tessdata** <https://github.com/tesseract-ocr/tessdata> \
> Speed : Faster than tessdata-best \
> Accuracy : Slightly less accurate than tessdata-best

> **tessdata-best** `(Recommended for video games)` <https://github.com/tesseract-ocr/tessdata_best> \
> Speed : Slowest \
> Accuracy : Most accurate

> **tessdata-fast** <https://github.com/tesseract-ocr/tessdata_fast> \
> Speed : Fastest \
> Accuracy : Least accurate

### Page Segmentation Modes

The PSM allows you to select a segmentation method dependent on your particular image and the environment in which it was captured

<table><thead><tr><th width="69" align="center"> </th><th>Page segmentation modes</th></tr></thead><tbody><tr><td align="center">1</td><td>Orientation and script detection (OSD) only.</td></tr><tr><td align="center">2</td><td>Automatic page segmentation with OSD.</td></tr><tr><td align="center">3</td><td>Automatic page segmentation, but no OSD, or OCR. (not implemented)</td></tr><tr><td align="center">4</td><td>Fully automatic page segmentation, but no OSD. (Default)</td></tr><tr><td align="center">5</td><td>Assume a single column of text of variable sizes.</td></tr><tr><td align="center">6</td><td>Assume a single uniform block of vertically aligned text.</td></tr><tr><td align="center">7</td><td>Assume a single uniform block of text.</td></tr><tr><td align="center">8</td><td>Treat the image as a single text line.</td></tr><tr><td align="center">9</td><td>Treat the image as a single word.</td></tr><tr><td align="center">10</td><td>Treat the image as a single word in a circle.</td></tr><tr><td align="center">11</td><td>Treat the image as a single character.</td></tr><tr><td align="center">12</td><td>Sparse text. Find as much text as possible in no particular order.</td></tr><tr><td align="center">13</td><td>Sparse text with OSD.</td></tr><tr><td align="center">14</td><td>Raw line. Treat the image as a single text line, bypassing hacks that are Tesseract-specific.</td></tr></tbody></table>


# OCRSpace

### Link

* <https://ocr.space/ocrapi>

### Custom - HTTP POST

URL:&#x20;

* `https://api.ocr.space/parse/image`

Content Type:&#x20;

* `application/x-www-form-urlencoded`

Headers:&#x20;

* `{}`

Body:

{% code overflow="wrap" %}

```json
{ 
   "base64Image":"data:image/png;base64,$IMAGE_BASE64", 
   "language": "jpn",
   "apikey": "YOUR_API_KEY_HERE"
}
```

{% endcode %}

Response Type:

* `JSON`

Response Query:

* `ParsedResults[0].ParsedText`


# Custom - Command Line

{% hint style="info" %}
Make sure the OCR engine you want to use is all set up on your computer and you can call it from the command line
{% endhint %}

### Variables

* $IMAGE\_PATH
* $IMAGE\_BUFFER
* $IMAGE\_BASE64

***

### Examples:

#### 1. Tesseract OCR

Github Page: <https://github.com/UB-Mannheim/tesseract/wiki>

* Command: \
  `"C:\Program Files\Tesseract-OCR\tesseract.exe" "$IMAGE_PATH" stdout -l jpn+eng --oem 3 --psm 6`
* Alt Command: \
  `tesseract "$IMAGE_PATH" stdout -l jpn+eng --oem 3 --psm 6`

#### 2. EasyOCR

Github Page: <https://github.com/JaidedAI/EasyOCR>

* Command: \
  `easyocr -l ja en -f "$IMAGE_PATH" --detail=0 --gpu=True`


# Custom - HTTP POST

{% hint style="info" %}
Make sure the OCR engine can handle HTTP POST Requests
{% endhint %}

### Variables

* $IMAGE\_BUFFER
* $IMAGE\_BASE64

***

### Example:

#### 1. Google Cloud Vision

**Docs:**

* <https://cloud.google.com/vision/docs>

**URL:**

* `https://vision.googleapis.com/v1/images:annotate?key=$YOUR_API_KEY`

**Content Type:**&#x20;

* &#x20;`application/json`

**Headers:**

* &#x20;**`{}`**

**Body:**

```
{
  "requests": [ 
    { 
      "image": { "content": "$IMAGE_BASE64" },
      "features": [ 
        { "type": "TEXT_DETECTION", "maxResults": 1 }
      ]
    }
  ]
}
```

**Response Type:**

* &#x20;`JSON`

**Response Query:**

* &#x20;`responses[0].fullTextAnnotation.text`


# OCR Settings

To open the OCR Settings, go to **Settings -> Modules -> OCR**.

***

### Copy to Clipboard

Automatically copies the recognized text to your clipboard after each OCR capture.

***

### Status Bar

Shows or hides the Status Bar at the bottom of the Capture Area window.

***

### Auto Hide Toolbar *(New)*

Enables or disables the automatic hiding of the Side Toolbar.

When enabled, the Side Toolbar will automatically hide so it does not obstruct your view during gameplay.

***

### Draw Bounding Box

Displays the bounding box outlines returned by the OCR engine around each detected text region.

This is useful for verifying which areas the OCR engine is detecting and recognizing.

***

### Auto Capture Interval (s)

Sets the time interval (in seconds) between each automatic capture when Auto Capture is active.

***

### Recording Mode *(New)*

Enables or disables Recording Mode *(Requires Relaunch)*.

**When Recording Mode is OFF (default):** The Hyper Overlay window is automatically hidden from screenshots and screen recordings. This allows the OCR Capture Area to capture the screen without being obstructed by the Hyper Overlay window, resulting in more accurate text recognition.

**When Recording Mode is ON:** The Hyper Overlay window will briefly flicker or hide the displayed text during OCR capture events, then show it again once the capture is complete.

{% hint style="info" %}
**Note:** Some screenshot or screen recording applications may fail to capture the screen when Recording Mode is OFF. If you experience this issue, try enabling Recording Mode.
{% endhint %}

***

### Tesseract Server

Enables or disables the Tesseract local server.

When enabled, text recognition using the Tesseract OCR engine will perform significantly faster compared to running without the server.

***

### EasyOCR Custom Languages

Configures the language models used by EasyOCR.

Enter the languages as a JSON string array of language codes separated by commas.

**Example:**

```
["ja", "en"]
```

For a list of supported language codes, refer to the EasyOCR documentation.


# OCR Master

The OCR Master window is a control center for OCR operations, offering several features designed to enhance text recognition accuracy and workflow efficiency.

The OCR Master window is a control center for OCR operations, offering several features designed to enhance text recognition accuracy and workflow efficiency.

<figure><img src="/files/O4On3S30H72v2Aa7Vu1N" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The OCR Master window is an exclusive feature available only in the **Pro Version**.
{% endhint %}

## **Opening OCR Master**

To open the OCR Master window:

* Press **Ctrl + M** in the Screen Capture, or
* Click **OCR Master** from the Menubar

***

## OCR Master Features

### **1. Preview**

The Preview section displays the captured screen image in real-time, showing you exactly what the OCR engine processes.

**Pre-processing Controls**

The OCR Master window provides direct access to pre-processing settings, allowing you to adjust them while viewing the results immediately.

* **Image Upscaler**
  * Increases the resolution of the captured image
  * Makes small or blurry text clearer and more recognizable
  * Useful for games with small font sizes
* **Image Filter**
  * **Black Text:** Optimizes for dark text on light backgrounds
  * **White Text:** Optimizes for light text on dark backgrounds
  * **Color Text:** Preserves text colors while removing background noise
* **Image Adjustments**
  * Adjust brightness, contrast, threshold, and other parameters
  * See the effect of each adjustment in real-time
  * Fine-tune settings for optimal text recognition

{% hint style="info" %}
**Note:** Pre-processing adjustments are primarily useful for traditional OCR engines (Tesseract OCR, Windows OCR). Modern and AI-based OCR engines may not require these adjustments.
{% endhint %}

### **2. Display Capture Sources**

Shows the current monitor display and the coordinates of the capture area in real-time.

### 3. **Hotkeys**

Customize keyboard shortcuts for quick access to OCR functions without interrupting your gameplay.

{% hint style="info" %}
Available key codes: <https://www.electronjs.org/docs/latest/api/accelerator#available-key-codes>
{% endhint %}

| Action               | Hotkey (default) |
| -------------------- | ---------------- |
| Capture              | Ctrl + Space     |
| Auto Capture         | Ctrl + Shift + A |
| Set Region           | Ctrl + Shift + R |
| Show/Hide OCR Screen | Ctrl + Shift + S |
| Open OCR Master      | Ctrl + Shift + M |

### 4. **Plugins**

This section will provide options for downloading and adding plugins to enhance the OCR application with additional features and integrations.

## ...


# Pre-processing

Pre-processing (or image processing) prepares the captured screen image before it's sent to the OCR engine for text recognition. The goal is to optimize the image so the OCR engine can recognize text

Pre-processing (or image processing) prepares the captured screen image before it's sent to the OCR engine for text recognition.

**Important:** Pre-processing is primarily useful for **traditional OCR engines** (Tesseract OCR and Windows OCR). If you're using **modern OCR engines** like Fast OCR or **AI-based engines** (Google Cloud Vision, Azure Cloud Vision, LLM-based engines), you can skip pre-processing as these engines handle various image conditions automatically.

<div data-full-width="false"><figure><img src="/files/m2CBTbrWAsgg1Xk7vJsp" alt=""><figcaption></figcaption></figure></div>

#### **When to Use Pre-processing**

Use pre-processing when:

* You're using **Tesseract OCR** or **Windows OCR**
* Game text has colored or complex backgrounds
* There's low contrast between text and background
* OCR accuracy is poor without adjustments

Skip pre-processing when:

* You're using **Fast OCR**, **EasyOCR**, or other modern engines
* You're using **AI-based engines** (Qwen 2.5 VL, GPT-4 Vision, Claude Vision)
* You're using **cloud-based engines** (Google Cloud Vision, Azure Cloud Vision)

***

### Pre-processing Options

#### **Image Upscaler** (OCR Master)

Increases the resolution or size of the captured image. Higher resolution can help the OCR engine recognize small or blurry text more accurately.

#### **Image Filter** (OCR Master)

Removes background colors and enhances text visibility. There are three filter options:

* **Black Text Filter**
  * Converts the image to show black text on a white background
* **White Text Filter**
  * Converts the image to show white text on a black background
* **Color Text Filter**
  * Preserves text colors while removing background

<figure><img src="/files/AoZvFSpwMjMIeQ1YeVVZ" alt=""><figcaption></figcaption></figure>

<div data-full-width="false"><figure><img src="/files/PbKDypKdfp8gsLSDmoLg" alt=""><figcaption></figcaption></figure> <figure><img src="/files/CXNzKLFK1kndRsvXmNE4" alt=""><figcaption></figcaption></figure></div>

#### Image Adjustments

Fine-tune the captured image for better text recognition:

* **Greyscale**&#x20;
  * Converts the image to black and white (removes all colors)
* **Normalize**
  * Automatically adjusts image brightness and contrast
  * Adjust the threshold value to make text stand out more clearly
* **Invert**
  * Swaps black and white colors in the image
* **Threshold**
  * Controls the contrast between text and background
  * Adjust the threshold value to make text stand out more clearly
* **Lightness**
  * Adjusts the overall lightness of the image
* **Brightness**
  * Adjusts how bright or dark the image appears
* **Sharpen**
  * Makes text edges more defined and clear


# Post-processing

Post-processing refines the OCR output after the text has been recognized. This step helps correct common OCR errors, remove unwanted characters, and format the text properly before translation.

Post-processing refines the OCR output after the text has been recognized. This step helps correct common OCR errors, remove unwanted characters, and format the text properly before translation.

**Note:** Post-processing is useful for **all OCR engine types**. Even modern and AI-based OCR engines may produce text that needs formatting or correction.

### **When to Use Post-processing**

Use post-processing when:

* OCR recognizes wrong characters consistently ("l" as "|", "0" as "O")
* You need to remove specific characters or symbols
* Text formatting needs adjustment. (line breaks, quotation marks)
* You want to standardize character patterns
* OCR output contains unwanted characters

### Regular Expression (RegExp)

Regular Expressions (RegExp) are patterns used to search and manipulate text. VNTranslator supports two types of RegExp operations:

#### 1. RegExp Matching

Identifies and extracts specific text patterns from the OCR output. Only text that matches the pattern will be kept.

**Use cases:**

* Extract only Japanese characters and ignore other symbols
* Keep only specific language characters
* Remove everything except the main dialogue text

**Example:**

This pattern matches and extracts only Japanese characters (Kanji, Hiragana, Katakana, and Japanese symbols).

{% code overflow="wrap" %}

```
["[一-龠]+|[ぁ-ゔ]+|[ァ-ヴー]+|[々〆〤]+|[⺀-⿕]+|[、-〿]+|[ㇰ-ㇿ㈠-㉃㊀-㍿]+", "gmu"]
```

{% endcode %}

For more details, see [RegExp Matching](/advanced/regexp/matching).

#### 2. RegExp Replacement (Search & Replace)

Searches for specific text patterns and replaces them with other text. This is the most commonly used post-processing technique.

**Use cases:**

* Fix common OCR recognition errors
* Replace wrong quotation marks with correct ones
* Remove unwanted characters or symbols
* Normalize text formatting
* Fix line breaks and spacing issues

**Common Examples:**

Replace quotation marks:

```
["『", "g", "「"]
["』", "g", "」"]
```

Remove music symbols:

```
["♪", "g", ""]
```

Fix ellipsis:

```
["。。。", "g", "..."]
```

Remove line breaks:

```
["(\r\n|\n|\r)", "gm", " "]
```

Fix common OCR errors:

```
["\\|", "g", "I"]
```

For more details, see [RegExp Replacement](/advanced/regexp/replacement).


# Understanding OCR and Improving Accuracy

This guide explains how OCR works in VNTranslator and provides practical tips to improve text recognition accuracy.

This guide explains how OCR works in VNTranslator and provides practical tips to improve text recognition accuracy.

**Note:** This guide primarily focuses on traditional OCR engines (Tesseract OCR and Windows OCR). If you're using modern OCR engines like Fast OCR, LLM-based engines (Qwen 2.5 VL, GPT-4 Vision, Claude Vision), or cloud-based engines (Google Cloud Vision, Azure Cloud Vision), you can skip most pre-processing adjustments as these engines handle complex backgrounds and colored text automatically.

## How OCR Works in VNTranslator

### **1. Screen Capture**

<figure><img src="/files/OC4mM6es1XhNHnnaCsBj" alt=""><figcaption></figcaption></figure>

The first step in the OCR process is capturing an image from the screen. The quality of the captured image significantly impacts the OCR engine's ability to recognize text accurately.

### **2. Pre-processing (Image Processing)**

> **For Traditional OCR Engines Only.**
>
> Pre-processing is primarily needed when using **Tesseract OCR** or **Windows OCR**. Modern OCR engines like **Fast OCR**, **LLM-based engines**, and **cloud-based engines** can handle various text conditions without pre-processing adjustments.

<figure><img src="/files/m2CBTbrWAsgg1Xk7vJsp" alt=""><figcaption></figcaption></figure>

During pre-processing, the image is adjusted to display black text on a white background. This contrast makes it easier for traditional OCR engines to recognize the text.

**When to use pre-processing:**

* Using Tesseract OCR or Windows OCR
* Game text has colored backgrounds
* Low contrast between text and background
* Need to improve recognition accuracy for traditional engines

**When pre-processing is NOT needed:**

* Using Fast OCR or modern OCR engines
* Using LLM-based engines (Qwen 2.5 VL, GPT-4 Vision, Claude Vision)
* Using cloud-based engines (Google Cloud Vision, Azure Cloud Vision)

### **3.** Selecting the OCR Engine

Text recognition accuracy depends heavily on the OCR engine you choose. VNTranslator supports three categories of OCR engines:

**Traditional OCR Engines** ⭐

* **Examples:** Tesseract OCR, Windows OCR
* **Best for:** Simple text with black text on white background
* **Limitations:** May struggle with colored text or complex backgrounds
* **Requires:** Pre-processing adjustments for better accuracy

**Modern OCR Engines** ⭐⭐⭐

* **Examples:** Fast OCR, EasyOCR
* **Best for:** Moderate background noise and multi-colored text
* **Advantages:** Better handling of various text conditions without pre-processing
* **Requires:** Minimal to no pre-processing

**AI-based OCR Engines** ⭐⭐⭐⭐⭐

* **Examples:** Google Cloud Vision, Azure Cloud Vision, Qwen 2.5 VL, GPT-4 Vision, Claude Vision
* **Best for:** Complex backgrounds, rotated text, and colored text
* **Advantages:** High accuracy without pre-processing, handles various text conditions automatically
* **Requires:** No pre-processing needed

For a complete comparison of OCR engines, see [OCR Engines](/user-guide/ocr/ocr-engines).

### **4. Post-processing**

After the OCR engine processes the text, the result will be displayed. If recognition is inaccurate, you can make corrections during post-processing using Regular Expressions (RegExp) to refine the results.

Post-processing is useful for all OCR engine types to:

* Remove unwanted characters
* Fix common recognition errors
* Format the output text

***

## Tips for Improving OCR Accuracy

**For Traditional OCR Engines (Tesseract, Windows OCR)**

1. **Ensure high-quality image captures:** The better the quality of the screen capture, the higher the accuracy of OCR. Avoid blurry or low-resolution images.
2. **Use effective pre-processing:** Adjust the image to have high contrast (black text on white background) to make text recognition easier for the OCR engine.
3. **Select appropriate threshold settings:** Experiment with threshold values in the pre-processing options to find the best setting for your game.

**For Modern and AI-based OCR Engines**

1. **Ensure high-quality image captures:** Good capture quality still helps, but these engines are more forgiving with image quality.
2. **Skip pre-processing:** Modern and AI-based OCR engines work best with the original image without pre-processing adjustments.
3. **Choose the right engine for your needs:**
   * Use **Fast OCR** for offline, fast recognition with moderate accuracy
   * Use **cloud-based engines** for highest accuracy with complex text
   * Use **LLM-based engines** for maximum flexibility and accuracy

**For All OCR Engine Types**

1. **Utilize post-processing:** If text recognition is incorrect or you want to remove specific characters, use RegExp during post-processing to refine the output.
2. **Position capture area correctly:** Make sure the capture area covers only the text dialogue box to avoid capturing unnecessary elements.
3. **Test different engines:** Try different OCR engines to find which works best for your specific game or visual novel.


# AutoTrans

Real-time in-game translation (no text floating outside the game).

## How to Translate Games with AutoTrans

AutoTrans applies real-time translation directly inside a game while you play, with no text floating outside the game window.

{% hint style="info" %}
AutoTrans is an exclusive feature of the Pro Version.
{% endhint %}

{% embed url="<https://youtu.be/z157wE96HZQ>" %}

{% hint style="info" %}
AutoTrans may not work with all games and can affect performance. Because it translates text in real time within the game, you may experience lag while the game waits for translation responses. This can cause lower frame rates or brief delays during gameplay.
{% endhint %}

### Supported Game Engines

* RenPy 8.x
* RenPy 7.x
* RenPy 6.99.x
* RPG Maker MV
* RPG Maker MZ
* Tyrano Builder
* Kirikiri (Experimental)

***

### Getting Started

<figure><img src="/files/sdyutNj2hEAnhJNAiVz5" alt=""><figcaption><p>VNTranslator Launcher</p></figcaption></figure>

1. Select **AutoTrans** from the module list
2. Click **Browse** and select the game executable
3. Click the **Start** button to launch the game with AutoTrans

{% hint style="info" %}
**Important:** AutoTrans does not create translation patches for games. The translations are injected directly into the game in real time. This means you need to run the game through AutoTrans each time you want to play with translations enabled.
{% endhint %}

***

### Features

<table><thead><tr><th width="309" valign="top">Feature</th><th>Description</th></tr></thead><tbody><tr><td valign="top"><a href="/pages/MSc3nnFOdxRaRFXwxUll">Translation Mode</a></td><td>Switch between real-time translation modes, including cached, non-cached, and RenPy-specific compatibility modes</td></tr><tr><td valign="top"><a href="/pages/0eBnsu5cF1tXgPAHepkU">Translation Settings</a></td><td>Filter which text gets translated by character or word count, and adjust line breaks, word wrap, and excluded strings</td></tr><tr><td valign="top"><a href="/pages/pBHAsA2EPz1YfOME7wUL">Mods</a></td><td>Customize RenPy dialogue box, text, and font styling, or apply RPG Maker MV/MZ gameplay mods</td></tr><tr><td valign="top"><a href="/pages/UwVHJ63tB2hXn6XvVPUY">Font Replacement</a></td><td>Fix blank boxes, question marks, or missing characters caused by fonts that don't support the translated language</td></tr><tr><td valign="top"><a href="/pages/DZnEjCz4ogbWF11yUHp4">Extract &#x26; Translate</a></td><td>Pre-translate all game text before playing instead of translating in real time, reducing lag</td></tr><tr><td valign="top"><a href="/pages/KSym1xmjx0MzMUXgrHdN">Steam Connect</a></td><td>Launch DRM-protected Steam games through the Steam client instead of directly from the executable</td></tr></tbody></table>

For a full walkthrough of the AutoTrans interface, including the Translation Editor, Import/Export Translation Memory, and other in-game controls, see [Interface Overview](/user-guide/autotrans/interface-overview).

***

### Tips for Better Performance

* **Use Translation Filters** to skip translating UI elements and translate only dialogue text
* **Choose a faster translation service** - Google Lite is typically the fastest option for text-heavy games
* **Keep Translation Cache enabled** so repeated lines don't need to be translated again
* **Reuse Translation Memory** by exporting it after playing and importing it next time
* **Use Extract & Translate** for the smoothest experience, since it pre-translates all text before you play

***

### FAQ: Using AutoTrans

<details>

<summary><strong>What is AutoTrans?</strong></summary>

AutoTrans is a VNTranslator feature that translates game dialogue in real time, applying the translation directly inside the game while you play, without floating windows or overlays.

</details>

<details>

<summary><strong>Is AutoTrans available in the free version?</strong></summary>

No. AutoTrans is an exclusive feature of the Pro Version.

</details>

<details>

<summary><strong>Why is my game lagging with AutoTrans, and how do I fix it?</strong></summary>

Real-time translation needs a moment to send text, get a translation response, and display it, which can cause lag, especially with text-heavy screens. Using Translation Filters, a faster translation service, Translation Cache, or Extract & Translate can all help. See [How Can I Improve Game Speed in AutoTrans?](/user-guide/autotrans/faq/how-can-i-improve-game-speed-in-autotrans) for details.

</details>

<details>

<summary><strong>Does AutoTrans create a permanent translation patch?</strong></summary>

No. AutoTrans injects translations directly into the game in real time rather than generating a translation file, so you need to run the game through AutoTrans each time you want translations active.

</details>

<details>

<summary><strong>The translated text shows blank boxes or question marks instead of characters - how do I fix this?</strong></summary>

This usually happens when the game's default font doesn't support the translated language. Use [Font Replacement](/user-guide/autotrans/font-replacement) to switch to a font that displays the translated text correctly.

</details>

<details>

<summary><strong>Can I customize how translations look or behave?</strong></summary>

Yes. [Translation Mode](/user-guide/autotrans/translation-mode) controls how translations are processed, [Translation Settings](/user-guide/autotrans/translation-settings) controls what gets translated and how it's formatted, and [Mods](/user-guide/autotrans/mods) can adjust dialogue box and text styling for supported engines.

</details>

<details>

<summary><strong>Can I use AutoTrans with DRM-protected Steam games?</strong></summary>

Yes. Some Steam games require the Steam client to be running and won't launch directly from their executable file. [Steam Connect](/user-guide/autotrans/steam-connect) lets AutoTrans launch the game through Steam instead.

</details>


# Interface Overview

## Pre-Launch Settings

Configure AutoTrans before launching the game. These settings determine how AutoTrans will behave during gameplay.

<figure><img src="/files/RGYWOsgE5yDWiB54nWmj" alt=""><figcaption></figcaption></figure>

#### Translation Mode

Select how AutoTrans processes and displays translations.\
[View all available translation modes →](/user-guide/autotrans/translation-mode)

#### Game Mods

Enable or disable game modifications that enhance AutoTrans functionality.

[Learn more about available mods →](/user-guide/autotrans/mods)

#### Game Font

Change the font displayed in the game to improve readability of translated text.

[See how to configure fonts →](/user-guide/autotrans/font-replacement)

***

## In-Game Controls

Access AutoTrans features while the game is running.&#x20;

<figure><img src="/files/X10W5VcnBjRSqboocgmn" alt=""><figcaption></figcaption></figure>

#### Translation Editor

Open the built-in editor to view, modify, or correct translations in real-time.

#### Translation Toggle

Enable or disable translations during gameplay.

#### Extract & Translate

Access the extraction and translation workflow for batch processing game text.

[Learn about Extract & Translate →](/user-guide/autotrans/extract-and-translate)

#### Restart MT (Machine Translation)

Restart the machine translation engine if it becomes unresponsive or produces errors.

**Use when:** Translation stops working or returns errors.

#### Clear Cookies

Clear cookies in the virtual browser window used for web-based translation services.

**Use when:** Translation stops working or returns errors.

#### Import TM (Translation Memory)

Load previously saved translations to use in the current session.

#### Export TM (Translation Memory)

Save current translations for reuse in future sessions.


# Translation Mode

**AutoTrans offers several translation modes to handle different game and compatibility issues.**

### Default

The standard mode for real-time translation.\
Since **v0.8.9-beta**, this mode uses cached translations by default to improve performance.

### RT + No Cache

Real-time translation without caching. Each text line is translated every time it appears.

### ~~RT + Cache~~ (old version)

~~Real-time translation with caching from older versions.~~

***

### RenPy: RT + Raw Text \[Experimental]

An alternative translation method for RenPy games that extracts raw text before formatting.\
**Tip:** Enable Auto-Correct in the translation menu when using this mode.

### RenPy: Legacy Version \[Vanilla]

An older, more stable version for RenPy games.\
You can use this option if both "Default" and "RT + Raw Text" modes don't work with\
the game


# Translation Settings

<figure><img src="/files/wVcDqq6GXLvNtke0pHEc" alt=""><figcaption></figcaption></figure>

### Translation Filters

Use these settings to filter which text should be translated. This helps improve performance and ensures only relevant text is translated.

* **Min. Characters**\
  Set the minimum number of characters required for text to be translated.
* **Max. Characters**\
  Set the maximum number of characters allowed for text to be translated.
* **Min. Words**\
  Set the minimum number of words required for text to be translated.
* **Max. Words**\
  Set the maximum number of words allowed for text to be translated.

{% hint style="info" %}
**Use Case:** In games that display a lot of text on screen (not just dialogue), you can increase the Min. Characters and Min. Words values to ensure only dialogue text is translated. This filters out UI elements, button labels, and short system messages.

**Example:**

* Set Min. Characters to 10 and Min. Words to 3 to skip translating short UI text
* This helps translate only meaningful dialogue while ignoring menu items and labels
  {% endhint %}

### Max. Line Length

Set the maximum number of characters per line in translated text.

***

### **Default** Excluded Strings

Use a list of words or phrases that should not be translated.

### Protect Tags (WIP)

### Auto-Correct

Automatically corrects strings, tags, and variables using the **Transcheck** feature.\
Any incorrect translations will be automatically replaced.

### Word Wrap&#x20;

Automatically adds line breaks in the translation.

### Extra Post-Translation

Additional regexp in post-translation.

### Replace `\n` with Line Breaks&#x20;

Replaces the string `\n` with actual line breaks.

### Remove Line Breaks

Removes all existing line breaks.


# Mods

<figure><img src="/files/yZ9ZB9kPRSuIsEwsI4bA" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Some mods may not be compatible and could cause the game to crash.
{% endhint %}

## RenPy

### GUI Customization

* **Dialogue Box**
  * Custom BG
  * BG Image
  * BG Color
  * BG Opacity
  * TBox Height
* **Character Name**
  * Size
  * Bold
  * Italic
  * ~~Align~~
  * Outline Size
  * Outline Color
  * Xpos
  * Ypos
* **Dialogue Text**
  * Size
  * Color
  * Bold
  * Italic
  * ~~Align~~
  * Outline Size
  * Outline Color
  * Xpos
  * Ypos

### Text Styles (Legacy)

This mod allows modification of text styles in RenPy. However, it may not work in some games that use custom styles.

***

## RPGM MV/MZ

* God Mode
* Ghost Mode
* Auto Attack Mode
* Unlimited Gold
* ~~Unlimited Items~~
* Instant Level Up
* Max Stats
* Font Size
* Game Speed


# Font Replacement

**This feature replaces the game's default font to ensure translated text displays correctly.**

Many games use fonts that only support specific languages, which causes problems when displaying translations in other languages.

**Without a compatible font, the game may show:**

* Blank boxes (□□□) instead of text
* Question marks (???) or incorrect symbols
* Missing characters or broken text

<figure><img src="/files/dz7lAF4OOvxWNrCttz22" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/7C8gyJFf9WytbF4cjnzQ" %}
[How to Change Font Type in RenPy?](/user-guide/autotrans/faq/how-to-change-font-type-in-renpy)
{% endcontent-ref %}


# Extract & Translate

**Extract & Translate pre-translates all game text before playing, reducing lag and improving performance during gameplay.**

<figure><img src="/files/TtgVlVNA5PQHqIzWo48I" alt=""><figcaption></figcaption></figure>

#### How it works

Unlike real-time translation which translates text as it appears (causing the\
game to wait for each translation), with Extract & Translate:

1. Extracts all text from the game files
2. Translates everything in advance
3. Injects translations back into the game

#### Supported game engines:

* RenPy
* RPG Maker MV
* RPG Maker MZ

#### Performance Settings

To speed up the translation process, increase the number of worker processes:

**Settings ➜ Translation ➜ Max Worker Processes**

{% hint style="danger" %}
**Important Warning**\
Using more workers increases translation speed but also increases the risk of IP blocking by translation services due to rate limits.
{% endhint %}

**Recommended Worker Settings:**

* **Google Lite/Google Web:** 1-3
* **Bing/Papago:** 1-2
* **DeepL Web:** 1
* **DeepL API:** 1-2
* **ALL MT API:** 1-3


# Steam Connect

**Steam Connect allows AutoTrans to launch games through the Steam client instead of directly from the executable file.**

#### Why is this needed?

Some Steam games have DRM protection or require Steam to be running.\
These games will not start or may show errors if launched directly from the .exe file.\
Steam Connect solves this problem by launching the game through Steam.

#### How to enable Steam Connect

Navigate to: **Settings ➜ Modules ➜ AutoTrans ➜ Steam Connect**


# RTL

## RenPy

{% hint style="info" %}
This script file works with most RenPy versions but may not support all
{% endhint %}

* Download the `vnt_rtl.rpy` file
* Copy the `vnt_rtl.rpy` file into game folder: `GAME_DIR\game\vnt_rtl.rpy`

{% file src="/files/xcrWEmpwkDT0Lj4PJsjZ" %}


# FAQ


# How Can I Improve Game Speed in AutoTrans?

This guide explains why AutoTrans can cause lag and how to improve performance during gameplay.

## Why does the game slow down and lag?

AutoTrans translates text in real-time as it appears on screen. The game must wait for each translation to complete before continuing. This causes lag or freezing, especially when:

* There is a lot of text on screen at once
* Menus or choice screens have many options
* The translation service response is slow
* The more text on screen = The longer the game waits = More lag

## Solutions to Improve Performance

#### **1. Use Translation Filters (Recommended)**

Prevent certain text from being translated to reduce processing time.

Go to [Translation Filters](/user-guide/autotrans/translation-settings) Settings and adjust Translation Filters to:

* Skip translating UI elements
* Translate only dialogue text

#### 2. Choose Faster Translation Services

Different translation services have different response speeds.

**Speed comparison (fastest to slowest):**

* **Google Lite** - Fastest option
* **Google Web** - Fast and reliable
* **DeepL API** - Fast with API key
* **DeepL Web** - Slower but higher quality

{% hint style="info" %}
**Recommendation:** Use Google Lite for games with heavy text. Switch to DeepL only if translation quality is more important than speed.
{% endhint %}

#### 3. Enable Translation Cache

Translation cache stores previous translations, so repeated text doesn't need to be translated again.

**Status:**

* Available from version **0.8.7**
* Enabled by default since **v0.8.9-beta**

#### 4. Reuse Translation Memory

If the game has been played before or has multiple versions, import the translation memory to avoid re-translating the same text.

**How to use:**

* **Export:** After playing, export the translation memory from AutoTrans
* **Save:** Keep the translation file for future use
* **Import:** When playing again or playing a similar version, import the translation memory

#### 5. Use Extract & Translate (Best for Performance)

For the smoothest experience, use Extract & Translate instead of real-time translation.\
Extract & Translate pre-translates all game text before playing, reducing lag during gameplay.

**Learn more:** [Extract & Translate Guide](/user-guide/autotrans/extract-and-translate)


# How to Change Font Type in RenPy?

This guide shows how to change the font in RenPy games using AutoTrans to ensure translated text displays correctly.

### Step 1: Configure Font Directory <a href="#how-to-add-fonts-in-photoshop-on-a-mac" id="how-to-add-fonts-in-photoshop-on-a-mac"></a>

{% hint style="info" %}
By default, the font directory in `C:\Windows\Fonts`
{% endhint %}

* Go to Settings
* In the left sidebar, click **Modules**
* Click the **AutoTrans** tab
* in the **Font directory** field, enter the font directory&#x20;
* in the **Font extensions** field, enter the font extensions

<div align="left"><figure><img src="/files/98EBDJoN0Rt8hzPJ3NYv" alt=""><figcaption></figcaption></figure></div>

### **Step 2:** Select Font in AutoTrans

Once the font directory is configured and fonts are placed in that folder, they will appear in the AutoTrans font dropdown list.

<div align="left"><figure><img src="/files/OeHOWIlIeOFBZpKdDgGj" alt=""><figcaption></figcaption></figure></div>

***

## Font Replacement Method

AutoTrans offers several methods to replace fonts in RenPy games.

{% hint style="info" %}
Font Replacement Method is used when changing the font doesn't work!
{% endhint %}

<figure><img src="/files/79gIjg7DWIc7YmgXRGQU" alt=""><figcaption><p>AutoTrans - Font Replacement</p></figcaption></figure>

### Available Methods:

#### **1. Default (Recommended)**

Replaces fonts in the standard RenPy font locations.

**Steps:**

* Select **Default**
* Click **Refresh** to scan for fonts
* Click **Select all fonts** to apply

#### 2. GUI files

Replaces fonts specifically in GUI-related files.

**Steps:**

* Select **GUI files**
* Click **Refresh**
* Click **Select all fonts** to apply

#### 3. All archive files

Replaces fonts in all RenPy archive files (.rpa files) without modifying the original files.

**Steps:**

* Select **All archive files**
* Click **Refresh**
* Click **Select all fonts** to apply

#### 4. All archive files + Overwrite&#x20;

{% hint style="danger" %}
&#x20;**WARNING: This method permanently modifies game files!**\
Always backup the game folder before using this option. This cannot be undone without restoring from backup.
{% endhint %}

Replaces fonts in all archive files and overwrites the original files.

**Steps:**

* **BACKUP THE GAME FIRST!**
* Select **All archive files**
* Click **Refresh**
* Enable **+Overwrite**
* Click **Select all fonts** to apply


# RenPy Games

Complete tool for translating RenPy visual novels.

## How to Translate Ren'Py Games

VNTranslator lets you translate Ren'Py visual novels in real time - no manual editing, no waiting for an official language patch. This guide covers all 3 translation methods, when to use each one, and how to fix the most common problems. Some methods may not work in every game.

### Translation Methods Overview

VNTranslator provides three methods for translating Ren'Py games:

<table><thead><tr><th valign="top">Method</th><th valign="top">Description</th><th valign="top">Requirements</th></tr></thead><tbody><tr><td valign="top"><strong>AutoTrans</strong></td><td valign="top">Applies translation directly inside the game in real time</td><td valign="top">VNTranslator Pro</td></tr><tr><td valign="top"><strong>RenPy Clipboard Plugin</strong></td><td valign="top">Translates text copied from the game's clipboard output, using an installed plugin file</td><td valign="top">One-time <code>.rpy</code> file copy</td></tr><tr><td valign="top"><strong>RenPy Clipboard Voicing</strong></td><td valign="top">Translates text copied from the game's clipboard output, using the game's built-in Clipboard Voicing feature</td><td valign="top">None - enabled from within the game</td></tr></tbody></table>

Each method is described in detail in its own section below, including setup steps and requirements.

***

### Method 1: AutoTrans (Real-time In-game Translation)

{% hint style="info" %}
AutoTrans is an exclusive feature of the Pro Version.
{% endhint %}

AutoTrans translates Ren'Py dialogue directly inside the game window while you play, with no text floating outside the game and nothing to copy into the game folder.

{% embed url="<https://youtu.be/z157wE96HZQ>" %}

**Step 1:** In the VNTranslator Launcher

* Select [**AutoTrans**](/user-guide/autotrans) from the module list
* Click **Browse** and select the game
* Click the **Start** button

The game launches with live translation applied automatically.

{% hint style="info" %}
Because AutoTrans translates text in real time, some games may show brief lag or lower frame rates while waiting for a translation response. AutoTrans also doesn't create a permanent translation patch - you'll need to run the game through AutoTrans each time you want the translation active.
{% endhint %}

***

### Method 2: RenPy Clipboard Plugin

The RenPy Clipboard Plugin reads game text as it's copied to your clipboard and translates it in real time.

**Step 1:** Download and copy `VNT-RenPy-Clipboard.rpy`

* Download the `VNT-RenPy-Clipboard.rpy` file
* Copy the file into the game directory: `GAME_DIR\game\[here]`
* Start a new game or continue your save (make sure in-game Clipboard Voicing is **not** enabled)

{% hint style="info" %}
Download the latest version of VNT-RenPy-Clipboard from <https://fazx.itch.io/vntranslator-plugins>
{% endhint %}

**Step 2:** In the VNTranslator Launcher

* Select [**Clipboard**](/user-guide/clipboard) from the module list
* Click the **Start** button

***

### Method 3: RenPy Clipboard Voicing

Clipboard Voicing is a native feature of the Ren'Py engine itself. In some games, however, the developer may have this feature disabled. When available, it can be paired directly with VNTranslator's Clipboard option, without installing the plugin file used in Method 2.

{% embed url="<https://www.youtube.com/watch?v=eWFADVUJylM>" %}

**Step 1:** Enable Clipboard Voicing in the game

* In the game, press **Shift + C** to enable clipboard voicing

**Step 2:** In the VNTranslator Launcher

* Select [**Clipboard**](/user-guide/clipboard) from the module list
* Click the **Start** button

**Troubleshooting Tip:**

Because Clipboard Voicing is part of the Ren'Py engine itself, it can capture more than just dialogue - including menu screens, time-related functions, and item menus - which may appear as junk text in the clipboard output. If this happens, use [**RegExp Replacement**](/advanced/regexp/replacement) in Pre-translation to clean it up before it reaches the translator.

For example, raw clipboard output might look like this:

```
Hello World.: +10!: -0!: -0!: --date-1: --date-2: bla.. bla.. bla..
```

RegExp Replacement lets you strip the `+10!`, `-0!`, and `--date` fragments so only "Hello World." gets sent for translation.

***

### FAQ: Translating Ren'Py Games with VNTranslator

<details>

<summary><strong>What methods does VNTranslator offer for translating a Ren'Py game?</strong></summary>

VNTranslator provides three methods: **AutoTrans**, which applies translation directly inside the game in real time; the **RenPy Clipboard Plugin**, which translates text copied from the game's clipboard output using an installed plugin file; and **RenPy Clipboard Voicing**, which uses the game's built-in Clipboard Voicing feature instead of the plugin. Each method has its own setup steps, described earlier in this guide.

</details>

<details>

<summary><strong>Can I translate a Ren'Py game without editing its script or files?</strong></summary>

Yes. AutoTrans, the RenPy Clipboard Plugin, and Clipboard Voicing all translate text without modifying the game's original `.rpy` scripts. AutoTrans needs no files added to the game at all; the RenPy Clipboard Plugin only requires copying one small `.rpy` file into the `game` folder; Clipboard Voicing needs no files at all, since it's already built into the game.

</details>

<details>

<summary><strong>Why does my Ren'Py translation show junk or garbled text?</strong></summary>

This usually happens with the Clipboard Voicing method, since it's part of the Ren'Py engine itself and can capture more than just dialogue - including menu screens, time-related functions, and item menus. Use [RegExp Replacement](/advanced/regexp/replacement) in Pre-translation to filter that junk text out before translation.

</details>

<details>

<summary><strong>Does AutoTrans work with every Ren'Py game?</strong></summary>

AutoTrans supports Ren'Py 8.x, 7.x, and 6.99.x. As with any real-time translation method, results can vary depending on how a specific game renders its text.

</details>

<details>

<summary><strong>How does VNTranslator apply translations to a Ren'Py game?</strong></summary>

VNTranslator translates Ren'Py dialogue in real time as you play. Depending on the method used, text is read either directly from the game (AutoTrans) or from the game's clipboard output (RenPy Clipboard Plugin and Clipboard Voicing), then translated and applied without permanently modifying the game's original script files.

</details>

<details>

<summary><strong>Do I need to know Python or coding to translate a Ren'Py game?</strong></summary>

No. All three VNTranslator methods are designed for non-technical users - you select an option in the Launcher and press Start. Coding knowledge is only useful if you want to go further with tools like RegExp Replacement.

</details>

<details>

<summary><strong>Is it legal to translate someone else's Ren'Py game?</strong></summary>

Playing a game with real-time translation for personal use is different from distributing a translated copy of someone else's game. If you plan to share your translation with others, it's best practice to ask the original developer for permission first, since the game's script and assets remain their intellectual property.

</details>

<details>

<summary><strong>Can I make a permanent translation patch instead of real-time translation?</strong></summary>

Yes. While AutoTrans, RenPy Clipboard Plugin, and Clipboard Voicing all translate live each time you play, you can still create a permanent patch. Start with Ren'Py's built-in translation-file feature (Generate Translations in the Ren'Py Launcher, or via `RENPY_LANGUAGE` and `RENPY_UPDATE_STRINGS`), which creates a `game/tl/<language>` folder with empty translation slots for every line in the game.

Normally, filling in that folder means translating each line by hand. To skip that step, VNTranslator also stores every translation you've made in a Translation Memory (`.db`) file. [RenPy TM Replacer](https://gist.github.com/garudamods/e1b83db03ef9ff613566c99e8d7af6e9) is a Python script that reads this file and automatically fills in the matching lines inside your `game/tl/<language>` folder, so your translation memory becomes a permanent patch instead of a real-time translation.

</details>

<details>

<summary><strong>Why is my game lagging after I enable AutoTrans?</strong></summary>

Real-time translation needs a moment to send text, get a translation response, and display it - so brief lag or a lower frame rate is expected on some games, especially the first time a line of dialogue appears. Repeated lines are cached and won't cause lag on future playthroughs.

</details>


# Unity Games

Translate Unity-based games in real-time with automatic text replacement.

## How to Translate Unity Games

VNTranslator can translate Unity-based games in real time using XUAT, an integration that connects VNTranslator with XUnity AutoTranslator and a Unity mod loader. This guide explains how the integration works, how to install it with the XUAT Installer, and what to check if a game isn't fully supported.

***

### How the Integration Works

XUAT connects three separate tools to translate a Unity game in real time:

* **XUnity AutoTranslator** extracts text from the game and injects the translated result back into it
* **A mod loader (BepInEx or MelonLoader)** loads XUnity AutoTranslator into the game
* **VNTranslator** acts as the translation engine endpoint - it receives the extracted text, translates it, and returns the result to XUnity AutoTranslator to be displayed in the game

<table><thead><tr><th valign="top">Tool</th><th valign="top">Integration</th><th valign="top">Source</th></tr></thead><tbody><tr><td valign="top"><strong>XUnity AutoTranslator</strong></td><td valign="top">Extracts and injects translated text into the game</td><td valign="top"><a href="https://github.com/bbepis/XUnity.AutoTranslator">https://github.com/bbepis/XUnity.AutoTranslator</a></td></tr><tr><td valign="top"><strong>BepInEx</strong></td><td valign="top">Unity mod loader (plugin framework)</td><td valign="top"><a href="https://github.com/BepInEx/BepInEx">https://github.com/BepInEx/BepInEx</a></td></tr><tr><td valign="top"><strong>MelonLoader</strong></td><td valign="top">Unity mod loader (plugin framework)</td><td valign="top"><a href="https://github.com/LavaGang/MelonLoader">https://github.com/LavaGang/MelonLoader</a></td></tr></tbody></table>

{% hint style="info" %}
XUnity AutoTranslator, BepInEx, and MelonLoader are independent open-source projects and are not developed by VNTranslator. The XUAT Installer simplifies downloading and installing them together - refer to each project's repository for its full license terms and latest updates.
{% endhint %}

For issues related to game compatibility or XUAT-specific problems, refer to the [XUnity AutoTranslator GitHub Issues page](https://github.com/bbepis/XUnity.AutoTranslator/issues).

***

### What is the XUAT Installer?

The XUAT Installer is a tool built into VNTranslator that simplifies installing XUnity AutoTranslator together with a mod loader into a Unity game, without manually downloading or placing any files yourself.

<div align="left"><figure><img src="/files/cOScxYGxliR8XaJKxMzw" alt=""><figcaption></figcaption></figure></div>

**In the VNTranslator Launcher**

1. Select **XUAT** from the module list
2. Click **Browse** and select the game
3. Click the **Start** button

Clicking **Start** opens the **XUAT Installer** window, where you configure:

* **Unity Engine** - automatically detects the game's build type (Mono x64/x86 or IL2CPP x64/x86)
* **Mod Loader** - choose **BepInEx** or **MelonLoader**. Use the button next to this field to browse and download available mod loader versions directly from GitHub
* **XUAT (XUnity AutoTranslator)** - choose the version to install. Use the button next to this field to browse and download available versions directly from GitHub

Once configured, click **Install** to set up the mod loader and XUnity AutoTranslator into the game automatically.

Once installed, the **Install** button is replaced with two buttons:

* **Launch Game** to start the game with XUAT already applied
* **Uninstall** to remove the mod loader and XUnity AutoTranslator from the game.

***

### Compatibility Notes

* **Not all Unity games are supported.** Compatibility depends on the Unity version, engine modifications, and anti-cheat systems.
* **Some games may crash or freeze** when using XUAT, especially games with custom Unity builds or protection systems.
* **Text frameworks vary.** Some games require enabling specific text frameworks in the configuration file. Refer to the [text frameworks section](https://github.com/bbepis/XUnity.AutoTranslator?tab=readme-ov-file#text-frameworks) of the XUnity AutoTranslator documentation for setup details.

***

### FAQ: Translating Unity Games with VNTranslator

<details>

<summary><strong>What is XUAT?</strong></summary>

XUAT is VNTranslator's integration with XUnity AutoTranslator, a third-party tool that extracts and translates text inside Unity-based games in real time. VNTranslator acts as the translation engine behind this integration.

</details>

<details>

<summary><strong>What's the difference between BepInEx and MelonLoader?</strong></summary>

Both are Unity mod loaders required to run XUnity AutoTranslator inside a game, but they're separate projects with different licenses - BepInEx is LGPL-2.1, MelonLoader is Apache License 2.0 - and different compatibility across games. The XUAT Installer lets you choose either one depending on which the target game supports.

</details>

<details>

<summary><strong>Does XUAT support IL2CPP games?</strong></summary>

Yes. The XUAT Installer automatically detects whether a game uses Mono or IL2CPP (x64/x86) and installs a compatible mod loader and XUnity AutoTranslator build accordingly.

</details>

<details>

<summary><strong>Why isn't all the text in my Unity game being translated?</strong></summary>

Some Unity games use text rendering frameworks that aren't enabled by default in XUnity AutoTranslator's configuration file. Check the [text frameworks documentation](https://github.com/bbepis/XUnity.AutoTranslator?tab=readme-ov-file#text-frameworks) and enable the framework that matches your game.

</details>

<details>

<summary><strong>Can using XUAT get me banned or cause issues in a game?</strong></summary>

Some games use anti-cheat systems that may detect or block mod loaders like BepInEx or MelonLoader, which can cause crashes or other issues. Check the compatibility notes above and the game's community before installing XUAT on games with active anti-cheat protection.

</details>

<details>

<summary><strong>How do I remove XUAT from a game?</strong></summary>

Open the XUAT Installer for that game through the **XUAT** module in the VNTranslator Launcher, then click **Uninstall**. This removes the mod loader and XUnity AutoTranslator from the game folder.

</details>

<details>

<summary><strong>Where can I get help if my game isn't supported by XUAT?</strong></summary>

For compatibility issues specific to XUnity AutoTranslator, BepInEx, or MelonLoader, refer to the [XUnity AutoTranslator GitHub Issues page](https://github.com/bbepis/XUnity.AutoTranslator/issues) or each project's own repository.

</details>

<details>

<summary><strong>How do I change the font size in a Unity game translated with XUAT?</strong></summary>

See the dedicated guide: [How to Change Font Size in Unity.](/user-guide/unity-games/how-to-change-font-size-in-unity)

</details>


# How to Change Font Size in Unity?

A guide to modifying font sizes in Unity games using the BepInEx framework and XUAT plugin.

{% hint style="info" %}
This method might not work for some games
{% endhint %}

### Step 1: Enable Console

* Open the file `"GAME_DIR\BepInEx\config\BepInEx.cfg"`
* In the \[Logging.Console] section, change "Enabled = false" to "Enabled = true"

{% code title="GAME\_DIR\BepInEx\config\BepInEx.cfg" overflow="wrap" %}

```ini
[Logging.Console]

## Enables showing a console for log output.
# Setting type: Boolean
# Default value: false
Enabled = true
```

{% endcode %}

### Step 2: Enable Text Path Logging

* Open the file `"GAME_DIR\BepInEx\config\AutoTranslatorConfig.ini"`
* In the \[Behaviour] section, change "EnableTextPathLogging=False" to "EnableTextPathLogging=True"

{% code title="GAME\_DIR\BepInEx\config\AutoTranslatorConfig.ini" overflow="wrap" %}

```ini
[Behaviour]
EnableTextPathLogging=True
```

{% endcode %}

### Step 3: Launch the game and find the Text Path in the Console

If configured correctly, a console window will appear, showing the Game Text and Text Path

{% code overflow="wrap" %}

```powershell
[Info   :XUnity.AutoTranslator] Setting text on '???' to '???' # <-- Game Text
[Info   :XUnity.AutoTranslator] Path : ??? # <-- Text Path
[Info   :XUnity.AutoTranslator] Level: ???
```

{% endcode %}

### Step 4: Creating a Resizer File

**Create a file named "resizer.txt"** into the folder "GAME\_DIR\BepInEx\Translation\en\Text\\".\
For example: "GAME\_DIR\BepInEx\Translation\en\Text\resizer.txt"

{% hint style="info" %}
You can create more than one of these files. Each file must be a .txt file with the name ending in "resizer". Example: mainmenu\_resizer.txt, dialogue.resizer.txt, \_resizer.txt
{% endhint %}

#### **Syntax:**

```ini
TextPath=Command
```

where available commands are:

* Commands that change the font size to a static size
  * `ChangeFontSizeByPercentage(double percentage)`: Where the percentage is the percentage of the original font size to reduce it to.
  * `ChangeFontSize(int size)`: Where the size if the new size of the font
  * `IgnoreFontSize()`: This can be used to reset font resize behavior that was set on a very 'non-specific' path.

For more information, visit: <https://github.com/bbepis/XUnity.AutoTranslator#ui-font-resizing>

***

### Example of the font resizer syntax in the Quickie Game:

<figure><img src="/files/MM2HrblKYSejWvlaXBwU" alt=""><figcaption></figcaption></figure>

{% code title="Console" %}

```powershell
[Info   :XUnity.AutoTranslator] Setting text on 'TMPro.TextMeshProUGUI' to 'Lorem Ipsum...'
[Info   :XUnity.AutoTranslator] Path : /UIManager/ui_conversation/limiter/panel_dialogue/normal/txtmeshDialogueNormal
[Info   :XUnity.AutoTranslator] Level: -1
[Info   :XUnity.AutoTranslator] Setting text on 'UnityEngine.UI.Text' to 'It is a long...'
[Info   :XUnity.AutoTranslator] Path : /UIManager/ui_conversation/limiter/choices/panel_choices/ui_conversation_option(Clone)/text
[Info   :XUnity.AutoTranslator] Level: -1
[Info   :XUnity.AutoTranslator] Setting text on 'UnityEngine.UI.Text' to 'Contrary to popular...'
[Info   :XUnity.AutoTranslator] Path : /UIManager/ui_conversation/limiter/choices/panel_choices/ui_conversation_option(Clone)/text
[Info   :XUnity.AutoTranslator] Level: -1
```

{% endcode %}

{% code title="resizer.txt" %}

```ini
/UIManager/ui_conversation/limiter/panel_dialogue/normal/txtmeshDialogueNormal=ChangeFontSizeByPercentage(0.75)
/UIManager/ui_conversation/limiter/choices/panel_choices/ui_conversation_option(Clone)/text=ChangeFontSizeByPercentage(0.75)
```

{% endcode %}

{% hint style="info" %}
ChangeFontSizeByPercentage(0.75)

* 0.5 = 50%
* 1 = 100%
* 1.5 = 150%
  {% endhint %}

{% code title="mainmenu\_resizer.txt" %}

```ini
/mainmenu/limiter/content/bg/info/butons/btnNewGame/Text=ChangeFontSize(16)
/mainmenu/limiter/content/bg/info/butons/btnLoadGame/Text=ChangeFontSize(16)
/mainmenu/limiter/content/bg/info/butons/btnOptions/Text=ChangeFontSize(16)
/mainmenu/limiter/content/bg/info/butons/btnCredits/Text=ChangeFontSize(16)
/mainmenu/limiter/content/bg/info/butons/btnQuit/Text=ChangeFontSize(16)

# Or for all groups "/mainmenu/limiter/content/bg/info/butons"

/mainmenu/limiter/content/bg/info/butons=ChangeFontSize(16)
```

{% endcode %}


# Tyrano Games

## **AutoTrans** (Real-time In-game Translation)

{% content-ref url="/pages/yVpRv6logs3AU8CYAVaH" %}
[AutoTrans](/user-guide/autotrans)
{% endcontent-ref %}

***

## Tyrano Clipboard (dialog text to clipboard)

**How to extract app.asar?**

* Use 7-Zip with plugin to open or extract app.asar
* Download Asar.64.dll, Asar.32.dll from <http://www.tc4shell.com/en/7zip/asar/>
* Put Asar.64.dll, Asar.32.dll into C:\Program Files\7-Zip\Formats

**Open the .\GAME\_DIR\resources\app\index.html in a text editor (VSCode/Noteped++), and then add a script:**

```javascript
<script type="text/javascript">
const tt=tyrano.plugin.kag.tag.text, vntranslator=tt.showMessage.bind(TYRANO), nc=navigator.clipboard;
tt.showMessage=(a,b,c)=>{ nc.writeText(a); return vntranslator(message_str=a,pm=b,isVertical=c); } 
</script>
```

<figure><img src="/files/qNkhIm8LehPyVa3ddU9T" alt=""><figcaption></figcaption></figure>


# TextractorCLI

**Extract text from visual novels and video games using a text hooker program.**

{% embed url="<https://www.youtube.com/watch?feature=youtu.be&v=zUNJrg3AUbo>" %}

## About Integration

**VNTranslator** serves as the translation engine endpoint in this integration. Textractor performs the actual text hooking and injection into the game process. If you encounter issues with specific games, please check the [Textractor GitHub Issues page](https://github.com/Artikash/Textractor/issues) for game-specific troubleshooting and solutions.

> #### **Important Notice**
>
> Textractor is not actively developed anymore. As a result, some newer visual novel games may not work properly.
>
> **Alternative Solution:** You can update the `texthook.dll` file located in your Textractor installation folder with a newer version that is still being maintained by the community to improve compatibility with recent games.
>
> **See the following references:**
>
> * [Community discussion and alternative builds](https://github.com/Artikash/Textractor/issues/868)
> * [Updated texthook.dll information](https://github.com/Artikash/Textractor/issues/868#issuecomment-1249146885)
> * [Latest community updates](https://github.com/Artikash/Textractor/issues/1383#issuecomment-2700040978)

## Integration Methods

There are two ways to integrate Textractor with VNTranslator:

#### **Method 1: TextractorCLI (Command-line Integration)**

This method uses the command-line version of Textractor for direct integration.

#### **Method 2: Clipboard Integration** (Recommended Alternative)

This method uses the Textractor GUI application with the "Copy to Clipboard" extension, combined with VNTranslator's [Clipboard Translator](/user-guide/clipboard) feature. This approach is more stable and easier to set up.

***

## Method 1: TextractorCLI Integration

#### **Get Started**

To get started, you need to download **Textractor** and configure it in **VNTranslator**.

#### **Step 1: Download & Install Textractor**

* Visit the [Textractor Github releases page](https://github.com/Artikash/Textractor/releases)
* Download the **Textractor-5.x.x-Setup.exe** file
* Run the installer and follow the installation prompts

#### **Step 2:** Configure the integration&#x20;

![](/files/9caLMrXUvWZaT2nSohIk)

* Open **Settings** in VNTranslator
* In the left sidebar, click **Modules**
* Click the **TextractorCLI** tab
* In the **TextractorCLI Path** field, enter the path to **TextractorCLI.exe**\
  Example paths:
  * `C:\Textractor\x86\TextractorCLI.exe` (for 32-bit)     &#x20;
  * `C:\Textractor\x64\TextractorCLI.exe` (for 64-bit)&#x20;

#### **Step 3:** Launch with VNTranslator

* Select **TextractorCLI** from the module list
* Select the **Game Process**
* Select **Extra Window** from the output list
* Click the **Start** button

#### Important: Antivirus Exception

{% hint style="danger" %}
You must add `TextractorCLI.exe` as an exception in both Windows Defender and your antivirus software. Text hooking programs are often flagged as potentially malicious because they inject code into running processes.
{% endhint %}

***

## **Method 2: Clipboard Integration (Recommended)**

This method uses the Textractor GUI program (`Textractor.exe`) with its built-in "Copy to Clipboard" extension, combined with VNTranslator's [Clipboard Translator](/user-guide/clipboard) feature.

#### **Step 1: Enable Copy to Clipboard Extension in Textractor**

1. Launch **Textractor.exe** (not TextractorCLI.exe)
2. In the Textractor window, click on **Extensions**
3. In the Extensions window, **right-click** and select **"Add extension"**
4. A file browser will appear. Navigate to and select **"Copy to Clipboard.xdll"**
5. Once added, the extension will be automatically enabled and will copy extracted text to your clipboard

#### **Step 2: Clipboard Translator in VNTranslator**

1. Open **VNTranslator**
2. Select **Clipboard** from the module list
3. Select **Extra Window** from the output list
4. Click the **Start** button

#### **Step 3: Attach Textractor to Your Game**

1. Launch your visual novel or game
2. In Textractor, click **Attach to game** or use the **Process** menu
3. Select your game's process from the list
4. Textractor will begin hooking text from the game

#### **Step 4: Select the Correct Text Hook**

1. Advance the text in your game (click through dialogue)
2. In Textractor, you will see multiple text threads appear
3. Click on different threads to identify which one contains the game dialogue
4. Once you find the correct thread, Textractor will automatically copy the text to clipboard
5. VNTranslator will detect the clipboard change and display the translation


# Translation Services

VNTranslator supports a wide range of popular machine translation services\
To view the complete list of supported services, check the [**Translation Services**](/features/translation-services) section.

**What's the best translation service?**\
This is one of our most frequently asked questions. The short answer: choose the one that works best for you! 😊

However, AI/LLM-based translation services generally produce better results than traditional machine translation services, as they allow you to provide additional context for more accurate translations.

***

{% content-ref url="/pages/zc4cKuMHHiTfMqFUcRA6" %}
[Installing, Uninstalling, and Updating](/user-guide/translation-services/installing-uninstalling-and-updating)
{% endcontent-ref %}

{% content-ref url="/pages/QSb5pu8iiaJOrMta9OqF" %}
[Service Settings](/user-guide/translation-services/service-settings)
{% endcontent-ref %}

{% content-ref url="/pages/EhmWONFp5n5lQ5Dj2JDk" %}
[Glossary](/features/translation/glossary)
{% endcontent-ref %}

{% content-ref url="/pages/q3F3xrWhZ70ERkZtWBUd" %}
[LLMs](/advanced/llms)
{% endcontent-ref %}

{% content-ref url="/pages/fL9kcNzjbByGeixa7s5v" %}
[Custom MT](/advanced/custom-mt)
{% endcontent-ref %}


# Installing, Uninstalling, and Updating

### Installing Translation Services

* Open **Settings**
* Navigate to the **Translation Services**
* Use the following tabs:
  * **Available**: Displays translation services available for installation
  * **Installed**: Displays engines that are already installed
  * **Updates**: Displays available updates for your installed services

### Uninstalling Translation Services

To uninstall an engine:

* Go to **Service Settings**
* Click the **Uninstall** button


# Service Settings

This section contains the basic configuration options for each machine translation engine.

<figure><img src="/files/nSgNZ6SBom83s76wtbhg" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To open Service Settings:&#x20;

* From Launcher: Menubar -> Translator -> Double Click on the Service Name
* From Settings: Settings -> Translation Engines -> Click on the Service Name
  {% endhint %}

### Web Scraping

* **Show Browser**\
  Opens a browser window showing the translation page.
* **User Agent**\
  Specifies the browser identity string. (Not recommended to change unless necessary)

### LLM Web

* **Show Browser**\
  Opens a browser window showing the LLM translation page.
* **Combine Prompt with Source Text**\
  When enabled, the source text will be merged with the custom prompt.
* **Prompt**\
  The base prompt used by the LLM.

### LLM API

* **API Key**\
  Your personal API key used to authenticate with the LLM service. Keep this private and secure.
* **Model**\
  The name of the LLM model you want to use.
* **System Prompt**\
  A base instruction for the AI model that sets the context or behavior for all translations.
* **Temperature**\
  Controls the randomness in the output. Lower values produce more focused and deterministic results, while higher values produce more creative output.
* **Max Tokens**\
  The maximum number of tokens (words/characters) the model can generate in a single response. Higher limits may increase costs.
* **Top P**\
  An alternative method to control creativity. Works together with temperature - lower values limit responses to more likely outcomes.
* **Frequency Penalty**\
  Reduces the likelihood of the model repeating the same phrases. Higher values result in less repetition.
* **Presence Penalty**\
  Encourages the model to introduce new topics. Higher values result in more diverse content.


# DeepL API

{% hint style="info" %}
DeepL offers free API access that allows you to translate up to 500,000 characters per month for free.\
If you need more than that, you can purchase a DeepL API Pro subscription and it costs $5.49 / month + Usage based price
{% endhint %}

* Visit <https://www.deepl.com/pro#developer>

<figure><img src="/files/crj6q0qirYiaCyBZAwow" alt=""><figcaption></figcaption></figure>

* Complete the subscription process.
* After you have subscribed, go to your Account <https://www.deepl.com/account/summary> and under the tab with the same name you will find your API key.

<figure><img src="/files/ONjZ5p5719tBhR9KfqL2" alt=""><figcaption></figcaption></figure>

* Copy the API key, then in the VNTranslator go to Service Settings and enter your key.


# Clear Cookies & Site Data

### From App Launcher

* Menubar -> Quick Actions -> Clear cookies & site data

***

### From App Command

{% hint style="info" %}
Requires a minimum version: **Pro 0.8.6 & Neo 0.8.0**
{% endhint %}

<div align="left" data-full-width="false"><figure><img src="/files/n2KNXiMEPBAdcAmLaxVV" alt=""><figcaption></figcaption></figure></div>

* Go to Settings -> App Settings
* Type `$app.cookies.clear` in the Run Command and Enter
* Relaunch the app

***

### Manually **Delete Cookie File (**&#x41;lternativ&#x65;**)**

* Exit the VNTranslator App
* Open the Run Command (Windows key + R)
* Type `%appdata%\VNTranslator\Network` in the Open box, and click the OK option to confirm
* Next, delete the Cookies file


# Integration


# How to use Magpie with extra window

<figure><img src="/files/OSaUDpja5GuoFnR5fdnv" alt=""><figcaption></figcaption></figure>

* Visit Magpie's github page <https://github.com/Blinue/Magpie>, then download the latest version of Magpie
* Extract the zip and run **Magpie.exe**
* In the Magpie, click **Defaults**
* Change the **Scaling mode** to **Lanczos/FSR/ACNet**
* Change the **Capture method** to **Desktop Duplication**
* In the game window, Press **WinKey+Shift+A** to trigger fullscreen ON/OFF

{% hint style="info" %}
Make sure the game is running in windowed mode, not maximized or fullscreen mode and
&#x20;make sure to position the extra window (game overlay) on top of the game window
{% endhint %}


# LLMs

VNTranslator can be integrated with popular LLMs either through APIs for advanced features or via web browser for free access.

{% embed url="<https://youtu.be/LSXqwUIiwpY>" %}

## **Free LLM Integration via Web Browser**

#### No API configuration required

Access LLMs directly using the integrated web browser by logging into each LLM service.\
Please note:

* Some LLM services may require specific configurations or regional access
* Using a VPN may cause websites to fail loading

<table><thead><tr><th width="299">Name</th><th width="158" align="center">Combine Prompt</th><th width="117" align="center">Stream</th><th align="center">Automation</th></tr></thead><tbody><tr><td>ChatGPT Web </td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Gemini Web </td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Claude Web </td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Mistral Web</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>DeepSeek Web</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Grok Web</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr></tbody></table>

***

## Integrating LLM via API

<table><thead><tr><th width="306">Name</th><th width="155" align="center">System Prompt</th><th width="117" align="center">Stream</th><th align="center">Context History</th></tr></thead><tbody><tr><td>OpenAI API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Gemini API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Claude API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Mistral API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>DeepSeek API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>Grok API </td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>OpenRouter API</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>-------------------------</td><td align="center">-</td><td align="center">-</td><td align="center">-</td></tr><tr><td>OpenAI Conversation v1.3 (legacy)</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td></tr><tr><td>OpenAI Translate v1.3 (legacy)</td><td align="center">❌</td><td align="center">❌</td><td align="center">❌</td></tr><tr><td>GeminiAI v1.1 (legacy)</td><td align="center">❌</td><td align="center">❌</td><td align="center">❌</td></tr></tbody></table>

{% hint style="info" %}
You can set the LLM parameter in the MT Settings. To open MT Settings:

* In the Launcher: Menubar -> Translator -> Double-click on the translator option
  {% endhint %}

<figure><img src="/files/5lQRVHRkbNZZ6F2gXy2M" alt=""><figcaption></figcaption></figure>

### System Prompt

Customize the initial instructions provided to the translation system to fine-tune translation.

### Stream

Enable real-time streaming to receive translation results progressively instead of waiting for the entire translation to complete.

### Context History

Improve translation accuracy by using context from previously translated text.

* **Context Source**\
  Choose the context source:
  * **New Translation History**: Uses the most recent translations from the current session.
  * **Translation Memory**: Uses stored translation memory entries.
* **Max Context Entries**\
  Set the maximum number of previous entries to use as context.

  **Note:** More entries consume more tokens, which may increase processing time and API costs.

### Links

* **OpenAI** - [https://platform.openai.com](https://platform.openai.com/)
  * Models: <https://platform.openai.com/docs/models#models-overview>
* **GeminiAI** - [https://aistudio.google.com](https://aistudio.google.com/)
  * Models: <https://ai.google.dev/gemini-api/docs/models/gemini>
* **ClaudeAI** - [https://console.anthropic.com](https://console.anthropic.com/)
  * Models: <https://docs.anthropic.com/en/docs/about-claude/models>
* **MistralAI** - [https://console.mistral.ai](https://console.mistral.ai/)
  * Models: [https://docs.mistral.ai/getting-started/models/models\_overview](https://docs.mistral.ai/getting-started/models/models_overview/)
* **DeepSeek** - [https://platform.deepseek.com](https://platform.deepseek.com/)
  * Models: <https://api-docs.deepseek.com/quick_start/pricing>
* **GrokAI** - [https://console.x.ai](https://console.x.ai/)
  * Models: <https://docs.x.ai/docs/models>
* OpenRouter - <https://openrouter.ai/>
  * Models: <https://openrouter.ai/models>

***

## Offline (Run LLMs Locally)

<div align="left"><figure><img src="/files/EFmse1iyTHQnl7znOMRq" alt=""><figcaption></figcaption></figure></div>

* ✅ **LM Studio** (Recommended)
  * Download and Install LM Studio from <https://lmstudio.ai/>
  * Download a model and load it in LM Studio
  * Start the server in LM Studio
  * Enter the model name in MT settings
* ✅ **GPT4All**
  * Download and Install GPT4All from <https://www.nomic.ai/gpt4all>

***

## **Content Filtering and Restrictions**

LLM services like ChatGPT, GeminiAI, and ClaudeAI have content filters that may block:

* Explicit, harmful, or offensive content
* Text that violates the AI provider's terms of service
* Sensitive or restricted material, including copyrighted content

**What Happens with Restricted Content?**

If your text is flagged:

* The LLM may refuse to translate it
* You may receive an error message or generic response instead of a translation

**Tips to Avoid Issues**

* **Try a different model or version:** If one model flags your text, switch to another.\
  Note that newer versions often have stricter filters.
* **Experiment with prompt engineering:** Search online for effective prompt engineering techniques.\
  Be careful to follow the AI provider's terms of service when doing this.


# System Prompt

You can customize the system prompt to match the context of the visual novel you are translating. This helps the model produce more accurate and context-aware translations.

{% hint style="info" %}
This is an example system prompt for translating from Japanese to English.
{% endhint %}

{% code overflow="wrap" %}

```
You are a professional translator specializing in Japanese visual novels.
Your task is to translate the provided Japanese text into English accurately and naturally, while preserving the original context, tone, and emotional nuance.
Please follow these strict guidelines:
- Provide only the English translation. Do not include explanations, comments, notes, or questions.
- Preserve the original style, characterization, tone, and emotional nuances of dialogue and narration.
- Retain cultural references intact or adapt them carefully when direct translation might cause confusion, ensuring the original meaning remains clear.
- Translate honorifics, idiomatic expressions, and unique Japanese phrasing into natural, equivalent English expressions that retain their contextual meaning.
- If the text is meaningless, unclear, or untranslatable sentences, output the original source text without modification.
- If the text includes explicit or sensitive content, translate them faithfully and clearly while maintaining the original intention and tone.
```

{% endcode %}

## Optional

{% code overflow="wrap" %}

```
- Below is a list of the main characters, including their names in Japanese and English, adjusted for consistency and context throughout the translation:
-- 木崎 司 - Kizaki Tsukasa - Male (Protagonist, Description);
-- 綾峯 依吹 - Ayamine Ibuki - Female (Main Character, Description);
-- 日次 舞白 - Hinami Mashiro - Female (Main Character, Description);
- Your translations must consistently reflect the immersive storytelling experience characteristic of visual novels.
- Do not translate or modify variables and tags enclosed within brackets or curly braces, such as [...], {...}, or <...>. Always leave these exactly as they appear.
```

{% endcode %}

## LLM Web

{% code overflow="wrap" %}

```
...
...
...

Respond with "OK" to confirm you understand these instructions. After that, for any Japanese text provided, respond only with the English translation, no explanations, no comments, no notes, just the translated text.
```

{% endcode %}


# LM Studio

LM Studio is a tool that allows you to run large language models (LLMs) locally on your computer. You can integrate it with VNTranslator to provide high-quality translations.

## 1. Download LM Studio

Visit the official **LM Studio** website and download the app <https://lmstudio.ai/>

## 2. Download an LLM Model

<figure><img src="/files/dUGrcku0fEvsWdu75PoR" alt=""><figcaption></figcaption></figure>

In this example, we will use **Gemma 3 12B** as the model

* Open **LM Studio** and click on the **Discover** tab in the left sidebar
* In the pop-up window, choose **Model Search** and enter the name of the model you want
* Click **Download** to download the model to your computer

## 3. Run the LLM Model

<figure><img src="/files/bwjqooqEvcQ06Elw0ARp" alt=""><figcaption></figcaption></figure>

* From the top menu in **LM Studio**, select the model you downloaded to start running it

## 4. Start the Server in LM Studio

<figure><img src="/files/d8ADxwZx3KNSN97UJp7T" alt=""><figcaption></figcaption></figure>

* Click on the **Developer** tab in the left sidebar
* Then click **Start Server**

{% hint style="info" %}
**Note:** The default server endpoint is: `http://localhost:1234/`
{% endhint %}

## 5. Configure VNTranslator

<figure><img src="/files/gObQVBqBmFALpnMBCCdj" alt=""><figcaption></figcaption></figure>

* In the MT Settings, enter the **model name** you started in **LM Studio** into the **Model** field


# OpenAI API

Settings ➜ Translation ➜ MT Engines ➜ Custom ➜ Configure

## Step 1: Create an API key in OpenAI Platform

* Visit <https://platform.openai.com/account/api-keys>
* Click on **Create new secret key**
* Name your new API key and click **Create secret key**
* And copy the API Key

## Step 2: Install OpenAI API

Go to Settings ➜ Translation Services ➜ Available ➜ Open API


# GeminiAI API

## Step 1: Create an API key in Google AI Studio

* Visit: <https://aistudio.google.com/>
* Click on **Get API Key**
* Click **Create API key in new project** \
  If you want to create an API key in existing project, click on Create API key in existing project and select the project.
* And copy the API Key

## Step 2: Install GeminiAI API

Go to Settings ➜ Translation Services ➜ Available ➜ Gemini API


# DeepSeek API

Settings ➜ Translation ➜ MT Engines ➜ Custom ➜ Configure

## Step 1: Create an API key in DeepSeek Platform

* Visit <https://platform.deepseek.com/api_keys>
* Click on **Create new secret key**
* Name your new API key and click **Create API Key**
* And copy the API Key

## Step 2: Install DeepSeek API

Go to Settings ➜ Translation Services ➜ Available ➜ DeepSeek API


# Custom MT

{% hint style="info" %}
Requires VNTranslator version Pro 0.8.6 or later, and Neo 0.8.0 or later.\
Note: Some parameters are only available in the Pro version.
{% endhint %}

## To open Custom MT:

* From Launcher: Menubar -> Translator -> Double Click on the Service Name
* From Settings: Settings -> Translation Services -> Click on the Service Name

<figure><img src="/files/0N2xGZCuscNKWtEkaE6V" alt=""><figcaption></figcaption></figure>

> The Launcher does not automatically reload the configuration after you save or update Custom MT code. To reload the configuration, switch to another translation service and then back to Custom MT (Custom MT → DeepL Web → Custom MT).

## Configuration

Write the **Custom MT code** using the **JSON object structure** format:

* **configVersion**: `number`
* **name**: `string`
* **title**: `string`
* **description**: `string`
* **version**: `string`
* **icon**: `object` \<default: string>
* **schema**: `Array of objects` - [\[Schema\]](/advanced/custom-mt/schema)
* **formBuilder**: `Array of objects` - [\[FormBuilder\]](/advanced/custom-mt/form-builder)
* **lang**: `object` \<source: Array, target: Array>
  * **source**: `Array of objects` <{name: string, value: string}>
  * **target**: `Array of objects` <{name: string, value: string}>
* **request**: `object` - [\[Request\&Response\]](/advanced/custom-mt/request-and-response)
* **components**: `object` - [\[Components\]](/advanced/custom-mt/components)

```json
{
    "configVersion": 3,
    "name": "openai",
    "title": "OpenAI",
    "description": "Translate natural language text",
    "version": "1.0",
    "icon": {
        "default": "openai.png"
    },
    "schema": [],
    "formBuilder": [],
    "lang": {
        "source": [
            { "name": "Japanese", "value": "japanese"}
        ],
        "target": [
            {"name": "English", "value": "english"}
        ]
    },
    "request": {},
    "components": {}
}
```


# Schema

This is a configuration section of [Custom MT](/advanced/custom-mt). Use this configuration to declare variables that will be stored locally, such as API keys for Machine Translation services.

## Object Structure

* **type**: `string`
* **name**: `string`
* **default**: `string|number`
* **required**: `boolean`
* **message**: `string` - error message displayed when validation fails

```json
{
    "schema": [
        { "type": "string", "name": "api_key", "default": "", "required": true, "message": "Required an API Key" },
        { "type": "string", "name": "formality", "default": "default", "required": true },
        { "type": "number", "name": "preserve_formatting", "default": 0, "required": true },            
    ]
}
```


# Form Builder

This is a configuration section of [Custom MT](/advanced/custom-mt). Use this configuration to create Machine Translation settings forms with various form elements.

## Object Structure

* **type**: `string`
  * "string"
  * "number"
  * "object"
* **form**: `string`
  * "input-text"
  * "input-number"
  * "input-range"
  * "input-password"
  * "select"
  * "textarea"
* **name**: `string`
* **title**: `string`
* **default**: `string|number`
* **options**: `Array of objects` <{name: string, value: string}> <mark style="color:$warning;">(optional)</mark>
* **styles**: `object` (optional)
* **launcher**: `object` \<show: boolean, fullwidth: boolean> <mark style="color:$warning;">(optional)</mark>

```json
{
    "formBuilder": [
        { "type": "string", "form": "input-text", "name": "api_key", "title": "API Key*", "default": "",
            "launcher": { "show": true }
        },        
        { "type": "string", "form": "select", "name": "formality", "title": "Formality", "default": "default",
            "options": [
                { "name": "Default", "value": "default" },
                { "name": "Formal", "value": "more" },
                { "name": "Informal", "value": "less" },
                { "name": "Formal (if available)", "value": "prefer_more" },
                { "name": "Informal (if available)", "value": "prefer_less" }
            ],
            "launcher": { "show": true }
        },
        { "type": "string", "form": "select", "title": "Preserve Formatting", "name": "preserve_formatting", "default": "0",
            "options": [
                { "name": "No (default)", "value": "0" },
                { "name": "Yes", "value": "1" }
            ],
            "launcher": { "show": true }
        }
    ]
}
```


# Request & Response

This is a configuration section of [Custom MT](/advanced/custom-mt). This section contains the core configuration for Machine Translation requests.

## Variables

* `$ID`
* `$SOURCE_TEXT` or `$ORIGINAL_TEXT`
* `$TRANSLATED_TEXT`
* `$SOURCE_LANG`
* `$TARGET_LANG`

Schema variables can be used in the configuration with the syntax `$SCHEMA_NAME`.

For example:

```json
{
    "schema": [
        { "type": "string", "name": "api_key", "title": "API Key", "default": "", "required": true, "message": "Required an API Key" },
    ],
    "request": {
        "method": "http_post",
        "url": "http://127.0.01/?key=$API_KEY"
        "options": {
            "headers": {
              "Authorization": "Bearer $API_KEY",
              "Content-Type": "application/json"
            }
        }        
    }
}
```

***

## Parameters

#### **method**: `string`

* "web\_scraping"
* "http\_get"
* "http\_post"
* "web\_llm"

#### **initialUrl**: `string` <mark style="color:$warning;">(optional)</mark>

The initial URL to visit before making the actual request (for web scraping).

#### **ur**l: `string`

The endpoint URL for the Machine Translation service.&#x20;

#### **encodeURI**: `boolean` <mark style="color:$warning;">(optional)</mark>

Escapes characters using UTF-8 code units, with each octet encoded in the format `%XX`, left-padded with 0 if necessary. Lone surrogates in UTF-16 do not encode any valid Unicode character.\
Reference: [encodeURI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)

#### **encodeURIComponent:** `boolean` <mark style="color:$warning;">(optional)</mark>

Uses the same encoding algorithm as `encodeURI`.\
Escapes all characters except: `A–Z a–z 0–9 - _ . ! ~ * ' ( )`\
Reference: [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)

#### **encodeURIExtra:** `string` <mark style="color:$warning;">(optional)</mark>

Additional function to replace URI using a regular expression. For example: `["%2F", "g", "\\%2F"]`

#### userAgent: `string` <mark style="color:$warning;">(optional)</mark>

Custom User-Agent string for the HTTP request.

#### **querySelector:** `string`

Returns the first element within the HTML document that matches the specified selector or group of selectors.\
Reference: [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)

#### **querySelectorAll:** `string` <mark style="color:$warning;">(optional)</mark>

Returns a static NodeList representing a list of HTML elements that match the specified group of selectors.\
Reference: [querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll)

#### **queryProperty:** `string`

Specifies which property to extract from the selected HTML element:

* "value" - property of the HTMLDataElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDataElement/value)
* "innerText" - property of the HTMLElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
* "textContent" **-** property of the Node [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
* "innerHTML" - property of the HTMLElement [\[Reference\]](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)

#### **body:** `object`

The request body for POST requests. Can contain variables like `$SOURCE_TEXT`, `$SOURCE_LANG`, and `$TARGET_LANG`.

#### **options:** `object` <mark style="color:$warning;">(optional)</mark>

Additional request options.

* **headers** - Set custom request headers:
  * X-Custom-Header: `string`
  * Authorization: `string`
  * Content-Type: `string`

#### responseType: `string`

* "string" - set response type as string
* "json" - set response type as json

#### **responseQuery:** `string`

***

### Parsing JSON Responses from HTTP Requests

JSON responses can be parsed using the `responseQuery` parameter.

The `responseQuery` parameter is only used for `http_get` and `http_post` methods when the response type is set to `json`.

To navigate through nested JSON objects, use dot notation (`.`) to separate field names. Array elements can be accessed using bracket notation with an index (e.g., `[0]`).

**Example JSON Response:**

```json
{
  "text": "Hello 1",
  "words": [
    { "text": "Hello 2" },
    { "text": "Hello 3" }
  ]
  "lines": {
    "text": "Hello 4",
    "sub": {
      "text": "Hello 5"
    }        
  }
}
```

| responseQuery  | Result  |
| -------------- | ------- |
| text           | Hello 1 |
| words\[0].text | Hello 2 |
| lines.sub.text | Hello 5 |

***

***

## Examples

### 1. Web Scraping Method

<div align="left"><figure><img src="/files/e4AD2suCWLblRybyoQCU" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("web\_scraping")
* **url**: `string`
* **querySelector**: `string`
* **queryProperty**: `string`

```json
{
    "request": {
        "method": "web_scraping",
        "encodeURI": false,
        "encodeURIComponent": true, 
        "initialUrl": "https://localhost:8080",
        "url": "https://localhost:8080/?sl=$SOURCE_LANG&tl=$TARGET_LANG&text=$SOURCE_TEXT",    
        "querySelector": "span[lang=$TARGET_LANG]",
        "queryProperty": "innerText"
    }
}
```

***

### 2. HTTP GET Method

<div align="left"><figure><img src="/files/8yuvb0oD5m0dzzIrsJ0W" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("http\_get")
* **url**: `string`
* **responseType**: `string`
* **responseQuery**: `string`

```json
{
    "request": {
        "method": "http_get",
        "encodeURI": false,
        "encodeURIComponent": false, 
        "url": "https://localhost:8080/translate?sl=$SOURCE_LANG&tl=$TARGET_LANG&text=$SOURCE_TEXT",
        "options": {},
        "responseType": "json",
        "responseQuery": "translate.result"
    }
}
```

***

### 3. HTTP POST Method

<div align="left"><figure><img src="/files/8yuvb0oD5m0dzzIrsJ0W" alt=""><figcaption></figcaption></figure></div>

#### Required Parameters

* **method**: `string` ("http\_post")
* **url**: `string`
* **body**: `object`
* **options**: `object`
  * **headers**: `object`
    * X-Custom-Header: string
    * Authorization: string
    * Content-Type: string
* **responseType**: `string`
* **responseQuery**: `string`

```json
{
    "request": {
        "method": "http_post",
        "encodeURI": false,
        "encodeURIComponent": false, 
        "url": "https://localhost:8080/translate",
        "body": {
            "text": "$SOURCE_TEXT",
            "source_lang": "$SOURCE_LANG",
            "target_lang": "$TARGET_LANG"
        }
        "options": {
            "headers": {
                "Authorization": "Bearer $API_KEY",
                "Content-Type": "application/json"
            }
        },
        "responseType": "json",
        "responseQuery": "translate.result"
    }
}
```


# Components

This is a configuration section of [Custom MT](/advanced/custom-mt). Components are declared as objects within the configuration:

```json
{
    "components": {
        "preTranslation": {},
        "postTranslation": {},
        "contextMemory": {},
        "usageChecker": {},
        "interceptorRequest": {}
    }
}
```

### preTranslation

Processes the source text before sending it to the translation service.

* **allowLineBreaks**: `boolean`
* **excludeStrings**: `string`
* **regexpMatch**: `string`
* **regexpReplace**: `string`

```json
{
    "components": {
        "preTranslation":{
            "allowLineBreaks": true,
            "regexpReplace": "[\"\\n\", \"g\", \"\\\\n \"]"
        }
    }
}
```

### postTranslation

Processes the translated text after receiving it from the translation service.

* **regexpMatch**: `string`
* **regexpReplace**: `string`

```json
{
    "components": {
        "postTranslation": {
            "regexpReplace": "[\"\\\\\\\\n\", \"g\", \"\\n\"]"
        }
    }
}
```

### contextMemory

Maintains context history for AI/LLM translations, allowing the model to reference previous dialogue for improved coherence and accuracy.

**Required Parameters**

* **schema**: `Array of objects` <{type: string, name: string, default: string|number|bool}>
* **formBuilder**: `Array of objects` <{type: string, form: string, name: string, default: string|number}>
* **components**: `object` - Component reference to schema name \<schema:string>

```json
{
    "schema": {
        { "type": "boolean", "name": "contextMemory.status", "default": true },
        { "type": "string", "name": "contextMemory.initial_prompt", "default": "" },
        { "type": "string", "name": "contextMemory.system_template", "default": "" },
        { "type": "string", "name": "contextMemory.user_template", "default": "[{ \"role\": \"user\", \"parts\":[{\"text\":\"$SOURCE_TEXT\"}] }]" },
        { "type": "string", "name": "contextMemory.assistant_template", "default": "[{ \"role\": \"model\", \"parts\":[{\"text\":\"$TRANSLATED_TEXT\"}] }]" },
        { "type": "string", "name": "contextMemory.data_source", "default": "new_translation" },
        { "type": "number", "name": "contextMemory.max_entries", "default": "1" },
    },
    "formBuilder": {
        { "type": "string", "form": "textarea", "width": "450", "name": "contextMemory.user_template", "default": "", "title": "User Template" },
        { "type": "string", "form": "textarea", "width": "450", "name": "contextMemory.assistant_template", "default": "", "title": "Assistant Template" },
        { "type": "string", "form": "select", "name": "contextMemory.data_source", "title": "Context Source", "default": "TM",
            "options": [
                { "name": "New Translation History", "value": "new_translation" },
                { "name": "Translation Memory", "value": "TM" }                
            ]
        },
        { "type": "number", "form": "range", "name": "contextMemory.max_entries", "title": "Max Context Entries", "default": "1", "min": "1", "max": "256", "step": "1" }

    },
    "components": {
        "contextMemory": {
            "schema": "contextMemory"
        }
    }
}
```

### usageChecker

* **interval**: `number` - Interval in milliseconds between usage checks
* **format**: `string` - Display format for usage information
* **request**: `object` - Request configuration for checking usage:
  * **method**: `string` - HTTP method (`"http_get"`, `"http_post"`)
  * **url:** `string` - API endpoint URL for usage information
  * **body**: `object` <mark style="color:$warning;">(optional)</mark> - Request body for POST requests
  * **options**: `object` <mark style="color:$warning;">(optional)</mark> - Additional request options:
    * **headers:** `object` - Custom request headers
  * **responseCountQuery:** `string` - JSON path to extract current usage count
  * **responseLimitQuery:** `string` - JSON path to extract usage limit

```json
{
    "components": {
        "usageChecker": {
            "interval": 60000,
            "format": "( $COUNT / $LIMIT )",
            "request": {
                "method": "http_get",
                "url": "https://api.deepl.com/v2/usage?auth_key=$API_KEY",
                "responseCountQuery": "character_count",
                "responseLimitQuery": "character_limit"
            }        
        }
    }
}
```

### interceptorRequest

Modifies the source text before sending it to the translation service.

* **prependSourceText**: `object` - Adds text before the source text:
  * **status**: `boolean` - Enable or disable prepending
  * **value**: `string` - Text to prepend
* **appendSourceText**: `object` - Adds text after the source text:
  * **status**: `boolean` - Enable or disable appending
  * **value**: `string` - Text to append
* **replaceSourceText**: `object` - Replaces the entire source text

```json
{
    "schema": {
        { "type": "boolean", "name": "interceptorRequest.prependSourceText", "default": false },
        { "type": "string", "name": "prompt", "default": "Translate the following text from $SOURCE_LANG to $TARGET_LANG: " }
    },
    "components": {
        "interceptorRequest":{
            "prependSourceText": {
                "status": false,
                "value": "$PROMPT"
            }         
        }
    }
}
```


# webLLM

This is a configuration section of [Custom MT](/advanced/custom-mt). The webLLM method allows interaction with web-based Large Language Models (LLMs) by automating browser interactions and capturing streaming responses.

## Parameters

* **method**: `string` - Set to "web\_llm"
* **callback**: `string` - Callback method for handling responses ("dataSync")
* **url**: `string` - Set to null when using webLLM method
* **initialUrl**: `string` - The initial URL of the web-based LLM interface to load
* **inputEvent**: `array of objects` - Sequence of browser interaction events:
  * **Selector:** Set element property \<selector: string, property: string, value: string>
  * **Selector with Event:** Trigger element event \<selector: string, property: string, newEvent?: string, options?: object>
  * **Sleep:** Wait for specified duration \<sleep: number> (duration in milliseconds)
* **streamAdapter**: `string` - Type of network adapter to intercept:
  * "xhr" - XMLHttpRequest
  * "fetch" - Fetch API
* **streamOverrideDelay**: `number` - Delay in milliseconds before overriding stream responses
* **streamType:** `string` - How to handle streaming data:
  * `append` - Append new data to existing content
  * `replace` - Replace content with new data
* **streamFormat:** `string` - Expected format of streaming data:
  * "json" - JSON format
  * "string" - Plain text format
* **streamFilter:** `object` - Filter criteria for capturing network requests:
  * **url:** `array of strings` - Filter by URL patterns
  * **method:** `array of strings` - Filter by HTTP methods (\["GET", "POST"])
  * **contentType:** `array of strings` - Filter by content type headers
* **streamCompleted:** `object` - Conditions to determine when streaming is complete:
  * **setTimeout:** `number` - Maximum wait time in milliseconds after last data received
  * **requestReadyState:** `number` - XMLHttpRequest ready state value indicating completion
  * **requestException:** `string` - Exception name that indicates stream completion
* **streamParser:** `array of arrays` - Pipeline of parsing operations applied to each stream chunk. Each pipeline is an array of parser objects with the following available operations:
  * **Validation Operations:**
    * `{"act": "isString"}` - Check if value is a string
    * `{"act": "isArray"}` - Check if value is an array
    * `{"act": "isObject"}` - Check if value is an object
    * `{"act": "isNotNull"}` - Check if value is not null
    * `{"act": "isNotEq", "value": string}` - Check if value is not equal to specified value
    * `{"act": "minChar", "value": number}` - Check if string length is at least the specified value
    * `{"act": "maxChar", "value": number}` - Check if string length is at most the specified value
  * **String Operations:**
    * `{"act": "trim"}` - Remove whitespace from both ends
    * `{"act": "split", "separator": string, "limit": number, "index": number}` - Split string and get element at index
    * `{"act": "replace", "find": string, "replace": string}` - Replace first occurrence
    * `{"act": "replaceAll", "find": string, "replace": string}` - Replace all occurrences
    * `{"act": "search", "text": string}` - Check if text exists in string
    * `{"act": "indexOf", "text": string}` - Get index of text in string
    * `{"act": "regexpMatch", "regexp": string, "global": boolean}` - Match using regular expression
    * `{"act": "regexpReplace", "regexp": string, "global": boolean, "replace": string}` - Replace using regular expression
  * **Conversion Operations:**
    * `{"act": "toJSON"}` - Parse string as JSON
    * `{"act": "toString"}` - Convert value to string
  * **Object Operations:**
    * `{"act": "getValue", "key": string}` - Extract value from object by key

```json
{
    "request": {
        "method": "web_llm",
        "callback": "dataSync",
        "initialUrl": "https://chatgpt.com/", 
        "url": null,
        "inputEvent": [
            {"selector": "#textarea", "property": "value", "value": "$SOURCE_TEXT"},
            {"sleep": 100},
            {"selector": "button", "property": "click"},
        ],
        "streamAdapter": "fetch",
        "streamOverrideDelay": 0,
        "streamFilter": {},
        "streamFormat": "string",
        "streamType": "append",
        "streamCompleted": {
            "setTimeout": 2500,
            "requestException": "AbortError"
        },
        "streamParser": [
            [
                {"act": "isString"},
                {"act": "search", "text": "data:"},
                {"act": "replace", "find": "data:", "replace": ""},
                {"act": "toJSON"},
                {"act": "isObject"},
                {"act": "getValue", "key": "v"},
                {"act": "isString"},
                {"act": "isNotNull"}
            ],
            [...],
            [...]
        ]
    }
}
```


# MT Kit

## Custom MT in VNTranslator

```json
{
    "configVersion": 3,
    "name": "mtkit",  
    "title": "mtkit",        
    "description": "",
    "schema": [],           
    "lang": {
        "source": [
            { "name": "Arabic", "value": "Arabic" },
            { "name": "Bulgarian", "value": "Bulgarian" },
            { "name": "Chinese", "value": "Chinese" },
            { "name": "Czech", "value": "Czech" },
            { "name": "Danish", "value": "Danish" },
            { "name": "German", "value": "German" },
            { "name": "Greek", "value": "Greek" },
            { "name": "English", "value": "English" },
            { "name": "Spanish", "value": "Spanish" },
            { "name": "Estonian", "value": "Estonian" },
            { "name": "Finnish", "value": "Finnish" },
            { "name": "French", "value": "French" },
            { "name": "Hungarian", "value": "Hungarian" },
            { "name": "Indonesian", "value": "Indonesian" },
            { "name": "Italian", "value": "Italian" },
            { "name": "Japanese", "value": "Japanese" },
            { "name": "Korean", "value": "Korean" },
            { "name": "Lithuanian", "value": "Lithuanian" },
            { "name": "Latvian", "value": "Latvian" },
            { "name": "Norwegian", "value": "Norwegian" },
            { "name": "Dutch", "value": "Dutch" },
            { "name": "Polish", "value": "Polish" },
            { "name": "Portuguese", "value": "Portuguese" },
            { "name": "Romanian", "value": "Romanian" },
            { "name": "Russian", "value": "Russian" },
            { "name": "Slovak", "value": "Slovak" },
            { "name": "Slovenian", "value": "Slovenian" },
            { "name": "Swedish", "value": "Swedish" },
            { "name": "Thai", "value": "Thai" },
            { "name": "Turkish", "value": "Turkish" },
            { "name": "Ukrainian", "value": "Ukrainian" }
	    ],
        "target": [
            { "name": "Arabic", "value": "Arabic" },
            { "name": "Bulgarian", "value": "Bulgarian" },
            { "name": "Chinese", "value": "Chinese" },
            { "name": "Czech", "value": "Czech" },
            { "name": "Danish", "value": "Danish" },
            { "name": "German", "value": "German" },
            { "name": "Greek", "value": "Greek" },
            { "name": "English", "value": "English" },
            { "name": "Spanish", "value": "Spanish" },
            { "name": "Estonian", "value": "Estonian" },
            { "name": "Finnish", "value": "Finnish" },
            { "name": "French", "value": "French" },
            { "name": "Hungarian", "value": "Hungarian" },
            { "name": "Indonesian", "value": "Indonesian" },
            { "name": "Italian", "value": "Italian" },
            { "name": "Japanese", "value": "Japanese" },
            { "name": "Korean", "value": "Korean" },
            { "name": "Lithuanian", "value": "Lithuanian" },
            { "name": "Latvian", "value": "Latvian" },
            { "name": "Norwegian", "value": "Norwegian" },
            { "name": "Dutch", "value": "Dutch" },
            { "name": "Polish", "value": "Polish" },
            { "name": "Portuguese", "value": "Portuguese" },
            { "name": "Romanian", "value": "Romanian" },
            { "name": "Russian", "value": "Russian" },
            { "name": "Slovak", "value": "Slovak" },
            { "name": "Slovenian", "value": "Slovenian" },
            { "name": "Swedish", "value": "Swedish" },
            { "name": "Thai", "value": "Thai" },
            { "name": "Turkish", "value": "Turkish" },
            { "name": "Ukrainian", "value": "Ukrainian" }
	    ]
    },
    "request": {
        "method": "web_scraping",
        "encodeURI": false,
        "encodeURIComponent": true,       
        "initialUrl": "http://127.0.0.1:5454/translate",   
        "url": "http://127.0.0.1:5454/translate?sl=$SOURCE_LANG&tl=$TARGET_LANG&text=$SOURCE_TEXT",        
        "querySelector": "body",                
        "querySelectorAll": null,
        "queryProperty": "innerText"
    }
}
```

## Python Script

{% hint style="info" %}
You will need python >= 3.10
{% endhint %}

```python
# VNTranslator - Custom MT Kit

from flask import Flask, request
import json
import requests
import urllib.parse

APP_DEBUG = True
APP_HOST = "127.0.0.1"
APP_PORT = 5454

OPENAI_API_URL = "https://api.openai.com/v1/chat/completions"
OPENAI_API_KEY = "YOUR_API_KEY"
OPENAI_MODEL = "gpt-4o-mini"
OPENAI_PROMPT = "You are a professional translator specializing in {SOURCE_LANG} to {TARGET_LANG} translation for Visual Novels. \
You will be provided with text, please translate it and provide the best translation: {SOURCE_TEXT}"

app = Flask(__name__)
@app.route('/translate', methods=['GET'])
def translate():

    print("===== New Request =====")
    print(f"{request.method} {request.path}")
    
    source_text = request.args.get("text", "")
    source_lang = request.args.get("sl", "Japanese")
    target_lang = request.args.get("tl", "English") 

    if not source_text:
        print(f"Err: Missing text!")
        return  f"Err: Missing text!", 400

    # Decode text & format prompt
    source_text = urllib.parse.unquote(source_text)
    prompt = OPENAI_PROMPT.format(SOURCE_LANG=source_lang, TARGET_LANG=target_lang, SOURCE_TEXT=source_text).strip()
    print(json.dumps({'source_lang': source_lang, 'target_lang': target_lang, 'text': source_text}, ensure_ascii=False, indent=4))
    print(f"Prompt: {prompt}")

    # Set header
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {OPENAI_API_KEY}",
    } 
    # Set data
    data = {
        "model": OPENAI_MODEL,
        "messages": [
            {"role": "system", "content": prompt},
            {"role": "user", "content": source_text},
        ],
        "temperature": 0.7,
    }

    # Send request
    try:
        response = requests.post(OPENAI_API_URL, headers=headers, json=data)
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        print(f"Err: Failed to request: {e}")
        return f"Err: Failed to request: {e}", 500

    # Extract response
    try:
        response_data = response.json()
        translation = response_data["choices"][0]["message"]["content"]
    except (KeyError, IndexError) as e:
        print(f"Err: Invalid response: {e}")
        return f"Err: Invalid response: {e}", 500
    
    # Return response
    print(f"Response: {translation}\n")
    return translation, response.status_code

if __name__ == '__main__':
    app.run(debug=APP_DEBUG, host=APP_HOST, port=APP_PORT)
```


# V1 & V2 (Archive)

Old configuration for version 0.7.x & <= 0.8.6-alpha

{% hint style="info" %}
Old configuration for version 0.7.x and <= 0.8.6-alpha
{% endhint %}

**Pro Version**&#x20;

* Settings ➜ Translation ➜ MT Engines ➜ Custom ➜ Configure ➜ Switch Editor to Code

**Public Version**

* Settings ➜ Machine Translation ➜ Translators ➜ Custom ➜ Configure ➜ Switch Editor to Code

***

## Web Scraping Method

* lang: `object`
  * source: `array[]`
  * target: `array[]`
* config: `object`
  * method: `string`
  * initialURL: `string`
  * scrapeURL: `string`
  * encodeURI: `boolean`
  * encodeURIComponent: `boolean`
  * querySelector: `string`
  * querySelectorAll: `string`
  * queryProperty: `string`
  * evaluateInterval: `number`
  * evaluateTimeOut: `number`
  * waitingTimeOut: `boolean` \**Deprecated*
  * evaluateRepeated: `boolean` \**Deprecated*

```json
{
  "lang": {
    "source": [
        { "name": "Japanese", "value": "japanese"}
    ],
    "target": [
        {"name": "English", "value": "english"}
    ]
  },
  "config": {
    "method": "scrape",
    "scrapeURL": "http://localhost:8080/?source=$SOURCE_LANG&target=$TARGET_LANG&text=$ORIGINAL_TEXT",
    "encodeURI": false,
    "encodeURIComponent": true,
    "querySelector": "body",               
    "queryProperty": "innerText",
    "evaluateInterval": 50,
    "evaluateTimeOut": 7000
  }
}
```

***

## HTTP GET

* lang: `object`
  * source: `array[]`
  * target: `array[]`
* config: `object`
  * method: `string`
  * getURL: `string`
  * getOptions: `object`
  * encodeURI: `boolean`
  * encodeURIComponent: `boolean`
  * responseParse: `boolean`
  * responseType: `string`
  * responseQuery: `string`

```json
{
  "lang": {
    "source": [
        { "name": "Japanese", "value": "japanese"}
    ],
    "target": [
        {"name": "English", "value": "english"}
    ]
  },
  "config": {
    "method": "get",
    "getURL": "https://api.deepl.com/v2/translate?auth_key=$API_KEY&source_lang=$SOURCE_LANG&target_lang=$TARGET_LANG&text=$ORIGINAL_TEXT",
    "getOptions": {},
    "encodeURI": false,
    "encodeURIComponent": true,
    "responseParse": true,
    "responseType": "json",
    "responseQuery": "translations[0].text",
  }
}
```

***

## HTTP POST

* lang: `object`
  * source: `array[]`
  * target: `array[]`
* config: `object`
  * method: `string`
  * postURL: `string`
  * postOptions: `object`
  * postData: `object`
  * encodeURI: `boolean`
  * encodeURIComponent: `boolean`
  * responseParse: `boolean`
  * responseType: `string`
  * responseQuery: `string`

```json
{
  "lang": {
    "source": [
        { "name": "Japanese", "value": "japanese"}
    ],
    "target": [
        {"name": "English", "value": "english"}
    ]
  },
  "config": {
    "method": "post",
    "postURL": "https://api.openai.com/v1/chat/completions",
    "postData": {
      "messages": [
        "role": "user",
        "content": "Translate the following $SOURCE_LANG text to $TARGET_LANG: $ORIGINAL_TEXT"
      ]
    },
    "postOptions": {
      "headers": {
        "Authorization": "Bearer *****",
        "Content-Type": "application/json"
      }
    },
    "encodeURI": false,
    "encodeURIComponent": false,
    "responseParse": true,
    "responseType": "json",
    "responseQuery": "choices[0].message.content"
  }
}
```


# OCR Server Kit

Running OCR with large models like EasyOCR, PaddleOCR, or SuryaOCR can be slow when executed directly via the command line because the model has to be loaded every time you run it. Using LocalServer helps resolve this by loading the model just once, which makes the recognition process significantly faster.

## Scripts

{% content-ref url="/pages/bojeyOnWjLnotFcimrV2" %}
[EasyOCR](/advanced/ocr-server-kit/easyocr)
{% endcontent-ref %}

{% content-ref url="/pages/GjVKy7Hg3YrGbB7DOg1x" %}
[SuryaOCR](/advanced/ocr-server-kit/suryaocr)
{% endcontent-ref %}

***

## HTTP Request

<div align="left"><figure><img src="/files/NhWnrEVr5BZu28s7cphF" alt=""><figcaption></figcaption></figure></div>

**Method:** `POST`

**URL:**

```
http://127.0.0.1:5353
```

**Content Type:** `application/json`

**Headers: `{}`**

**Body:**

```
{"image":"$IMAGE_BASE64", "langs": ["ja"]}
```

**Response Type:** `JSON`

**Response Query:** `fullText`

***

## HTTP Response

* **draw\_bounding\_box:** `Boolean`
* **fullText:** `String`
* **lines:** `Array[]`

```json
{
    "draw_bounding_box": true,
    "fullText": "Hello World",
    "lines": [
        {"text": "Hello", "w": 100, "h": 50, "x": 10, "y": 10},
        {"text": "World", "w": 125, "h": 50, "x": 55, "y": 10}
    ]
        
}
```


# EasyOCR

{% code title="vntocr\_easyocr.py" %}

```python
# Integration VNTranslator OCR with EasyOCR engine
# Version: 1.0
# Author: Fazx - GarudaMods | https://www.patreon.com/vntranslator

"""
# ==================================================================
# EasyOCR: https://github.com/JaidedAI/EasyOCR
# Required: python 3.10+ and PyTorch
# Install with: pip install easyocr
# ==================================================================
# Run this script with: python vntocr_easyocr.py
# In VNTranslator use Custom Engine - HTTP POST with configuration:
# -- URL: http://127.0.0.1:5353
# -- Content type: application/json
# -- Headers: {}
# -- Body: {"image":"$IMAGE_BASE64", "langs": ["ja"]}
# -- Response type: JSON
# -- Response query: fullText
# ==================================================================
# Languages (two-letter ISO) https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
# -- Japanese = ja
# -- English = en
# ==================================================================
"""

from flask import Flask, request, jsonify
from PIL import Image
from io import BytesIO
import base64
import re
import json
import numpy as np
import easyocr

APP_HOST = "localhost"
APP_PORT = 5353
APP_DEBUG = True

def parse_ocr_result(easyocr_result):
    full_text = ""
    lines = []

    for entry in easyocr_result:
        polygon = entry[0]
        text = entry[1]
        confidence = entry[2]
        x_min = int(min(point[0] for point in polygon))
        y_min = int(min(point[1] for point in polygon))
        x_max = int(max(point[0] for point in polygon))
        y_max = int(max(point[1] for point in polygon))
        w = x_max - x_min
        h = y_max - y_min
        x = x_min
        y = y_min
        lines.append({
            "text": text,
            "w": int(w),
            "h": int(h),
            "x": int(x),
            "y": int(y),
            "confidence": float(confidence)
        })
        full_text += text + " "

    full_text = full_text.strip()
    return {
        "fullText": full_text,
        "lines": lines
    }

def base64_to_numpy(base64_string):
    if not base64_string:
        raise ValueError("Base64 string is empty or missing")

    if "," in base64_string:
        base64_string = base64_string.split(",")[1]

    try:
        image_decode = base64.b64decode(base64_string)
        print("Base64 decoding successful")

        # open the image with PIL
        image = Image.open(BytesIO(image_decode))
        print(f"Image format: {image.format}, size: {image.size}")

        # convert PIL image to NumPy array
        image_np = np.array(image)
        print(f"Converted image to NumPy array with shape: {image_np.shape}")

        return image_np
    except Exception as e:
        raise ValueError(f"Image decoding failed: {e}")

############################################################

app = Flask(__name__)
default_langs = ["ja"]
reader = easyocr.Reader(default_langs)

@app.route("/", methods=["POST"])
def ocr_endpoint(): 
    global default_langs, reader

    try:
        print("\n\n=== OCR Request ===")
        print(f"Method: {request.method}")
        print(f"Headers: {dict(request.headers)}")
        
        if not request.is_json:
            print("Request is not JSON")
            return jsonify({"error": "Request must be JSON"}), 400
        
        data = request.get_json()

        # log payload
        print(f"Request JSON keys: {list(data.keys())}")

        # check image
        if "image" not in data:
            print("No image data")
            return jsonify({"error": "No image data"}), 400
        
        # decode base64 image
        try:            
            image = base64_to_numpy(data["image"])
        except Exception as e:
            print(f"Image decoding failed: {e}")
            return jsonify({"error": f"Image decoding failed: {str(e)}"}), 400

        # check langs
        langs = data.get("langs", ["ja"])
        try:
            if langs != default_langs:
                default_langs = langs
                reader = easyocr.Reader(default_langs)
        except Exception as e:
            print(f"Load model failed: {e}")
            return jsonify({"error": f"Load model failed: {str(e)}"}), 400
        print(f"langs: {langs}")

        # check draw bounding box
        draw_bounding_box = data.get("draw_bounding_box", False)
        print(f"draw_bounding_box: {draw_bounding_box}")

        # run ocr
        # https://github.com/JaidedAI/EasyOCR?tab=readme-ov-file#usage
        result = reader.readtext(image)
        print(f"OCR completed successfully: {result}")

        # parse result
        parsed_result = parse_ocr_result(result)       
        parsed_result["draw_bounding_box"] = draw_bounding_box
        json_result = json.dumps(parsed_result, indent=4, ensure_ascii=False)
        return json_result

    except Exception as e:
        print(f"Error request: {e}")
        return jsonify({"error": str(e)}), 500

if __name__ == "__main__":
    print(f"=== Starting OCR server {APP_HOST} on port {APP_PORT} ===")
    app.run(debug=APP_DEBUG, host=APP_HOST, port=APP_PORT)

```

{% endcode %}


# SuryaOCR

{% code title="vntocr\_suryaocr.py" %}

```python
# Integration VNTranslator OCR with SuryaOCR engine
# Version: 1.0
# Author: Fazx - GarudaMods | https://www.patreon.com/vntranslator

"""
# ==================================================================
# Surya OCR: https://github.com/VikParuchuri/surya
# Required: python 3.10+ and PyTorch
# Install with: pip install surya-ocr
# ==================================================================
# Run this script with: python vntocr_suryaocr.py
# In VNTranslator use Custom Engine - HTTP POST with configuration:
# -- URL: http://127.0.0.1:5353
# -- Content type: application/json
# -- Headers: {}
# -- Body: {"image":"$IMAGE_BASE64", "langs": ["ja"]}
# -- Response type: JSON
# -- Response query: fullText
# ==================================================================
# Languages (two-letter ISO) https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
# -- Japanese = ja
# -- English = en
# ==================================================================
"""

from flask import Flask, request, jsonify
from PIL import Image
from io import BytesIO
import base64
import re
import json
from surya.ocr import run_ocr
from surya.model.detection.model import load_model as load_det_model, load_processor as load_det_processor
from surya.model.recognition.model import load_model as load_rec_model
from surya.model.recognition.processor import load_processor as load_rec_processor

APP_HOST = "localhost"
APP_PORT = 5353
APP_DEBUG = True

def format_ocr_result(ocr_result):
    full_text = ""
    boxes = []

    for result in ocr_result:
        for box in result["text_boxes"]:
            bbox = box["bbox"]
            x, y = bbox[0], bbox[1]
            w, h = bbox[2] - bbox[0], bbox[3] - bbox[1]
            boxes.append({
                "text": box["text"],
                "w": w,
                "h": h,
                "x": x,
                "y": y
            })

    boxes.sort(key=lambda box: (box["y"], box["x"]))
    full_text = " ".join(box["text"] for box in boxes).strip()

    return {
        "fullText": full_text,
        "boxes": boxes
    }

def parse_ocr_result(ocr_result):
    if not isinstance(ocr_result, list):
        raise ValueError("ocr_result is not a list")

    parsed_results = []
    for result in ocr_result:
        text_lines = []
        for line in result.text_lines:
            text_lines.append({
                "polygon": line.polygon,
                "confidence": line.confidence,
                "text": line.text,
                "bbox": line.bbox
            })

        parsed_results.append({
            "text_boxes": text_lines,
            "languages": result.languages,
            "image_bbox": result.image_bbox
        })

    return format_ocr_result(parsed_results)

############################################################

app = Flask(__name__)
det_processor = load_det_processor()
det_model = load_det_model()
rec_model = load_rec_model()
rec_processor = load_rec_processor()

@app.route("/", methods=["POST"])
def ocr_endpoint():    

    try:
        print("\n\n=== OCR Request ===")
        print(f"Method: {request.method}")
        print(f"Headers: {dict(request.headers)}")
        
        if not request.is_json:
            print("Request is not JSON")
            return jsonify({"error": "Request must be JSON"}), 400
        
        data = request.get_json()

        # log payload
        print(f"Request JSON keys: {list(data.keys())}")

        # check image
        if "image" not in data:
            print("No image data")
            return jsonify({"error": "No image data"}), 400
        
        # decode base64 image
        try:
            image_decode = base64.b64decode(data["image"])
            image = Image.open(BytesIO(image_decode))
            print("Image successfully decoded from Base64")
        except Exception as e:
            print(f"Image decoding failed: {e}")
            return jsonify({"error": f"Image decoding failed: {str(e)}"}), 400

        # check langs
        langs = data.get("langs", ["ja"])
        print(f"langs: {langs}")

        # check draw bounding box
        draw_bounding_box = data.get("draw_bounding_box", False)
        print(f"draw_bounding_box: {draw_bounding_box}")

        # run ocr
        # https://github.com/VikParuchuri/surya?tab=readme-ov-file#from-python
        result = run_ocr([image], [langs], det_model, det_processor, rec_model, rec_processor)
        print(f"OCR completed successfully: {result}")
        
        """
        [OCRResult(
            text_lines=[
                TextLine(polygon=[[0.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]], confidence=0.0, text='String', bbox=[0.0, 0.0, 0.0, 0.0]),
                TextLine(polygon=[[0.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]], confidence=0.0, text='String', bbox=[0.0, 0.0, 0.0, 0.0]),
                TextLine(polygon=[[0.0, 0.0], [0.0, 0.0], [0.0, 0.0], [0.0, 0.0]], confidence=0.0, text='String', bbox=[0.0, 0.0, 0.0, 0.0])
            ], 
            languages=['ja'], image_bbox=[0.0, 0.0, 0.0, 0.0]
        )]
        """

        # parse result
        parsed_result = parse_ocr_result(result)       
        parsed_result['draw_bounding_box'] = draw_bounding_box
        json_result = json.dumps(parsed_result, indent=4, ensure_ascii=False)
        return json_result

    except Exception as e:
        print(f"Error request: {e}")
        return jsonify({"error": str(e)}), 500

if __name__ == "__main__":
    print(f"=== Starting OCR server {APP_HOST} on port {APP_PORT} ===")
    app.run(debug=APP_DEBUG, host=APP_HOST, port=APP_PORT)

```

{% endcode %}


# API Gateway

**Useful for developers & integration with third-party apps.**

## Getting started with API Gateway

1. Select the API Gateway option
2. Press Start button

### Endpoint

```
http://127.0.0.1:7755
```

{% hint style="info" %}
You can change the **port** in the module settings
{% endhint %}

### APIs

{% content-ref url="/pages/BhpykeF44J65eyx13pG3" %}
[Translate](/advanced/api-gateway/translate)
{% endcontent-ref %}

{% content-ref url="/pages/3Bj1xHTE4eAVEddqT2s8" %}
[Translation Memory](/advanced/api-gateway/translation-memory)
{% endcontent-ref %}

### Error Codes

* 403 - Forbidden
* 404 - Not Found
* 405 - Method Not Allowed


# Translate

### GET  /translate/?text=Hello World

**Parameters**

* text (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```json
{ translated : 'Halo Dunia', ... }
```

***

### POST  /translate

**Parameters**

* text (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```json
{ translated : 'Halo Dunia', ... }
```

***

## Custom Parameters

* **Source Text**
* **Response Content-Type**
* **Response Body**

```
Content-Type: application/json;
Body: {"id":"$ID", "text":"$SOURCE_TEXT", "translated":"$TRANSLATED_TEXT"}
-----
Content-Type: text/html;
Body: $ID<hr/>$SOURCE_TEXT<hr/>$TRANSLATED_TEXT
-----
Content-Type: text/plain;
Body: $TRANSLATED_TEXT
```

***

### GET  /translate/custom/?:source\_text=Hello World

**Parameters**

* source\_text (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```html
Halo Dunia 
```

***

### POST  /translate/custom

**Parameters**

* source\_text (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**&#x20;

```html
Halo Dunia 
```


# Translation Memory

### GET  /tm/:id

**Parameters**

* id (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```json
{ ... }
```

***

### GET  /tm/getall

**Example response**

```json
{ ... }
```

***

### PUT /tm/:id

**Parameters**

* id (string) <mark style="background-color:blue;">required</mark>&#x20;
* translated (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```json
{ ... }
```

***

### DEL  /tm/:id

**Parameters**

* id (string) <mark style="background-color:blue;">required</mark>&#x20;

**Example response**

```json
{ ... }
```

***

### GET  /tm/search/?text=Hello World\&max\_results=100

**Parameters**

* text (string) <mark style="background-color:blue;">required</mark>&#x20;
* max\_results (string)

**Example response**

```json
{ ... }
```


# RegExp

**Regular Expressions are patterns used to match character combinations in strings.**

## RegExp Matching

{% content-ref url="/pages/Q3gyFVNDXjtiG9XvHYDP" %}
[Matching](/advanced/regexp/matching)
{% endcontent-ref %}

## RegExp Replacement

{% content-ref url="/pages/ydiEWglXDrnOujpkWPxa" %}
[Replacement](/advanced/regexp/replacement)
{% endcontent-ref %}


# Matching

{% hint style="info" %}
Starting from Pro version **0.9.1-alpha**, VNTranslator supports writing native JS RegExp using the syntax: `/Regexp/flags.`

The instructions below describe the old syntax, which is still supported for compatibility.
{% endhint %}

## Syntax&#x20;

`["Regexp", "Flags"], [...]`

## Parameters

* **Regexp** \
  A regular expression object
* **Flags**\
  Regular expressions have optional flags that allow for functionality like global searching and case-insensitive searching

| Flag | Description                                                                                                                                                                                                                  |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `d`  | Generate indices for substring matches                                                                                                                                                                                       |
| `g`  | Find all matches rather than stopping after the first match                                                                                                                                                                  |
| `i`  | If `u` flag is also enabled, use Unicode case folding                                                                                                                                                                        |
| `m`  | Treat beginning and end characters (`^` and `$`) as working over multiple lines. In other words, match the beginning or end of *each* line (delimited by  or ), not only the very beginning or end of the whole input string |
| `s`  | Allows `.` to match newlines                                                                                                                                                                                                 |
| `u`  | Treat `pattern` as a sequence of Unicode code points                                                                                                                                                                         |

## Return Value

All results matching the complete regular expression will be returned

***

## Examples

```
["[0-9]", "g"], ["[a-zA-Z]+", "g"]
["\\p{sc=Latin}", "gu"]
["[^\\x00-\\x7F]+", "g"]
["[^\\u0000-\\u007F]+", "g"]
["[一-龠]+|[ぁ-ゔ]+|[ァ-ヴー]+|[々〆〤]+|[⺀-⿕]+|[、-〿]+|[ㇰ-ㇿ㈠-㉃㊀-㍿]+", "gmu"]
```


# Replacement

{% hint style="info" %}
Starting from Pro version **0.9.1-alpha**, VNTranslator supports writing native JS RegExp using the syntax: `/Regexp/flags.`

The instructions below describe the old syntax, which is still supported for compatibility.
{% endhint %}

## Syntax&#x20;

`["Regexp", "Flags", "newSubstr/replacerFunction"], [...]`

## Parameters

* **Regexp** \
  A regular expression object.
* **Flags**\
  Regular expressions have optional flags that allow for functionality like global searching and case-insensitive searching.

| Flag | Description                                                                                                                                                                                                                  |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `d`  | Generate indices for substring matches                                                                                                                                                                                       |
| `g`  | Find all matches rather than stopping after the first match                                                                                                                                                                  |
| `i`  | If `u` flag is also enabled, use Unicode case folding                                                                                                                                                                        |
| `m`  | Treat beginning and end characters (`^` and `$`) as working over multiple lines. In other words, match the beginning or end of *each* line (delimited by  or ), not only the very beginning or end of the whole input string |
| `s`  | Allows `.` to match newlines                                                                                                                                                                                                 |
| `u`  | Treat `pattern` as a sequence of Unicode code points                                                                                                                                                                         |

* **newSubstr (replacement)**\
  The String that replaces the substring specified by the specified regexp or substr parameter
* **replacerFunction (replacement)**\
  A function to be invoked to create the new substring to be used to replace the matches to the given regexp or substr

## Return Value

A new string, with all matches of a pattern replaced by a replacement

***

### Examples

```
#Replace JP Char:
["ロキ", "g", "Loki"], ["オーディン", "g", "Odin"], ["フェンリル", "g", "Fenrir"]

#Remove Vars & Tags:
["({[^}]*})|(<[^>]*>)|({[^}]*})|(\\[[^\\]]*])", "gm", ""]

#Bubstitution with BackReference:
["^(.*)$", "g", "Hi, $1"]
["(\\w+)\\s+\\[(\\d+)]", "g", "$1[$2]"]

```

| RegExp                                | Source Text                                 | Result             |
| ------------------------------------- | ------------------------------------------- | ------------------ |
| \[": ?(\d+)", "gm", ""]               | Character : Hello. : 10 : 09 : 10 : 30      | Character : Hello. |
| \["(\[^]\*):", "gm", ""]              | Day 29 - Monday: Morning: Character: Hello. | Hello.             |
| \[": (\[^]\*)", "gm", ""]             | Hello.: -AAA: +BBB: 123                     | Hello.             |
| \["Day((.\*?):){2}", "gm", ""]        | Day 29 - Monday: Morning: Character: Hello. | Character: Hello.  |
| \["(\b\S.+\b)(?=.\*\1\b)", "gms", ""] | Monday Monday Monday                        | Monday             |
|                                       |                                             |                    |


# OCR

{% embed url="<https://www.youtube.com/watch?v=1b3l6RLM0_Q>" %}

## Introduction

GX-OCR was originally planned as a new feature for VNTranslator. However, during development, we found that integrating it would make the configuration overly complex and potentially confusing for users. As a result, we decided to develop GX-OCR as a standalone application with several specialized features.

Key Features of GX-OCR:

* Optimized for Window Capture with multi-region support
* Region positions automatically adjust to the game window (e.g., when the window is moved or resized)
* Translated text appears in an overlay above the original text and can be customized (similar to the Hyper Overlay feature in VNTranslator)
* Only supports modern OCR engines with priority given to offline OCR engines
* Only supports translation services officially through API integration

## Download

* Patreon: <https://www.patreon.com/collection/1931982>
* Itch: <https://fazx.itch.io/gx-ocr>

***

## Interface

<figure><img src="/files/nWK4TOQvnsSBrKXTzsoG" alt=""><figcaption></figcaption></figure>

#### Dock Buttons

1. **Capture** (Double click to enable/disable auto capture)
2. **Region** (Double click to show/hide region)
3. **Image Source**
4. **OCR Mode**
5. **Settings**

***

## Quick Start

### 1. Screen and Window Scaling

{% hint style="info" %}
If your monitor is set to a scale greater than 100%, you need to adjust the screen capture and window capture scale settings
{% endhint %}

* Go to **Settings -> General**
* In the **Screen Capture** section, adjust the **Scale** value
* In the **Window Capture** section, adjust the **Scale** value

### 2. OCR Engine & Translation Service

Before using GX-OCR, configure your OCR Engine for text recognition and set up your preferred Translation Service.

{% hint style="info" %}
By default, the OCR Engine is set to `Rapid OCR - OpenVino (English, Chinese, Japanese)`
{% endhint %}

{% embed url="<https://app.guideflow.com/player/6kwjv5lczp>" fullWidth="false" %}

### 3. Game Overlay (Basic)

{% embed url="<https://app.guideflow.com/player/dr9lm5ecor>" %}


# FAQ

**Frequently asked questions.**

### **What's the difference between Pro and Public versions?**

The Pro version is exclusive to VNTranslator supporters and includes:

* AutoTrans
* Advanced OCR Features
* More Translation Features
* More Translation Services
* GM Lens Extension
* Dark Theme Support
* Discord Benefits (Supporter tag & private channel access)
* General Support

### How do I get the Pro version?

By becoming a supporter on [**Patreon**](https://www.patreon.com/vntranslator/membership), you will get access to the Pro version.\
Each tier includes different benefits, so choose the one that fits your needs.

Your account credentials for logging into the Pro version will be sent automatically to your Patreon email address after you subscribe. If you haven't received the email, please wait 1-5 minutes and check your Spam or Promotions folder.

{% hint style="info" %}
**Gift Membership:**\
If you subscribed through Patreon's gift payment method, please note that it may take several hours to receive your account credentials due to Patreon API delays.\
If you haven't received your account credentials within 24 hours, please send me a DM on Patreon for assistance.
{% endhint %}

{% hint style="info" %}
⚠️ **Note:** If you signed up for Patreon using a private relay or temporary email service (such as Apple Private Relay <xxx@privaterelay.appleid.com>, or other similar email providers), email delivery will fail because these services block emails from third-party app. Please update your Patreon account to use a regular email address to ensure successful delivery.
{% endhint %}

### What happens if I cancel my pledge on Patreon?

VNTranslator Pro with its exclusive features is available as long as you remain an active supporter. If you cancel your pledge, you will still have access to VNTranslator Pro until your next billing date. After that, your Pro access will end and you'll need to resubscribe to continue enjoying the exclusive features.

### How do I reset my password?

* On the signin window, click **Help, I can't sign in**
* Click **Reset your password**
* Enter your Patreon email and follow the on-screen instructions

### **What does "Device Limit Reached" mean?**

This message appears when you've reached the maximum number of devices allowed for your supporter tier.

**Device limits by tier:**

* Supporter — 1 device
* Supporter+ — 1 device
* Supporter++ — 2 devices
* Diamond Supporter — 3 devices

**How to resolve this:**

* Exit the application or Sign Out your account on the active device
* Wait for the session to expire on the other device (approximately 24-36 hours)

### How do I get the Supporter role on Discord?

The Discord Supporter role is added automatically when you link your Patreon account to Discord. Here's how to do it:

* Make sure you're supporting the project on Patreon
* Connect your Patreon account with your Discord account
* The role will be automatically added to your Discord

For step-by-step instructions, check out this official Patreon guide:\
<https://support.patreon.com/hc/en-us/articles/212052266-Getting-Discord-access>

### How do I fix "Too many failed attempts"?

* Wait a few hours before trying again, or send a direct message on [**Patreon**](https://www.patreon.com/vntranslator)

### What should I do if I have account issues?

If you're experiencing account problems such as signin issues or expired account status, please send a direct message on [**Patreon**](https://www.patreon.com/vntranslator) for assistance.

### Is VNTranslator Safe?

YES! VNTranslator is completely safe. No risky downloads and no viruses.

### Where can I report bugs or issues?

Please report bugs and issues in the **#report-an-issue** channel on [**Discord**](https://rebrand.ly/discord-garudamods).\
Make sure to read and use the reporting template provided in the channel.

### Where can I submit feedback or suggestions?

You can submit feedback or suggestions on [**Discord**](https://rebrand.ly/discord-garudamods).


# Troubleshooting


# Account

### Invalid email or password

**Cause:** Incorrect email or password entered.\
**Solution:** Make sure you enter the correct email and password. You can reset your password if you've forgotten it.

***

### Unregistered email

**Cause:** The email address is incorrect or not registered.\
**Solution:**

* Ensure you have an active subscription on Patreon.
* If you subscribed through Patreon's gift payment method, please wait a few hours as the Patreon API can be slow. If you haven't received your account credentials via email within 24 hours, please send me a DM on Patreon.

***

### Too many failed attempts

**Cause:** Too many login attempts have been made.\
**Solution:** Wait a few hours and try again.

***

### Your account has been blocked!

**Cause:** Your account has been temporarily blocked.\
**Solution:** Please send me a DM on Patreon for assistance.

***

### Membership Expired / Your subscription has expired

**Cause:** Your membership has expired.\
**Solution:**

* Please renew your subscription on Patreon.
* If you believe this is an error, please send me a DM on Patreon.

***

### Device not recognized

**Cause:** Device identification error occurred.\
**Solution:** Relaunch the application or restart your computer.

***

### Device Limit Reached

**Cause:** You have reached the maximum number of devices allowed for your supporter tier.\
**Solution:**

* Exit the application or sign out of your account on the active device.
* Wait for the session to expire on the other device (approximately 24-36 hours).
* Upgrade your tier on Patreon.

**Device limits by tier:**

* Supporter — 1 device
* Supporter+ — 1 device
* Supporter++ — 2 devices
* Diamond Supporter — 3 devices


# Launcher




---

[Next Page](/llms-full.txt/1)