Translators - BallonTranslator

The translator module converts source text to target language. BallonTranslator supports online services, offline models, and LLM-based translators.

Online Translation Services

Google Translate

Overview

Free Google Translate API. No API key required.

Google Translate has closed service in mainland China. Users in China need a VPN and must change URL to *.com in settings.

Configuration

from modules.translators import TransGoogle

translator = TransGoogle(
    lang_source='日本語',
    lang_target='English'
)

translation = translator.translate("こんにちは")

Parameters

Parameter	Type	Default	Description
`delay`	float	0.0	Delay between requests (seconds)

Supported Languages

Auto-detection
Chinese (Simplified/Traditional)
Japanese, Korean
English, French, German, Spanish, Italian
Portuguese, Russian, Dutch, Polish
Vietnamese, Thai, Arabic, Hindi
And many more…

Features

Free: No API key needed
Multi-language: Broad language support
Auto-detection: Can detect source language
Fast: Quick response times

DeepL

Overview

High-quality translation service. Requires API key.

Setup

Get API key from DeepL API
Configure in settings:

from modules.translators import DeeplTranslator

translator = DeeplTranslator(
    lang_source='日本語',
    lang_target='English',
    api_key='your-api-key-here'
)

Parameters

Parameter	Type	Default	Description
`api_key`	string	-	DeepL API key (required)
`delay`	float	0.0	Request delay
`formality`	selector	default	Tone (less/more/default/prefer_more/prefer_less)
`context`	editor	-	Context for translation
`preserve_formatting`	selector	disabled	Keep text formatting

Formality Support

Languages supporting formality settings:

German, French, Italian, Spanish
Dutch, Polish, Portuguese, Russian, Japanese

translator = DeeplTranslator(
    lang_target='Deutsch',
    formality='more'  # Formal tone
)

Context Feature

Provide context for better translations:

translator.params['context']['value'] = "This is from a fantasy manga about magic."
translation = translator.translate("魔法")

Supported Languages

Chinese (Simplified)
Japanese, Korean
English, German, French, Spanish, Italian
Portuguese, Brazilian Portuguese
Russian, Dutch, Polish
And more EU languages

Features

High Quality: Best-in-class translation
Formality Control: Adjust tone/politeness
Context-Aware: Provide context for accuracy
Formatting: Preserve text formatting

DeepLX (Free DeepL Alternative)

Overview

Free DeepL alternative using reverse-engineered API.

Setup Options

Self-hosted DeepLX

Deploy DeepLX
Configure endpoint:

translator = DeepLXTranslator(
    endpoint='http://localhost:1188/translate'
)

Vercel Deployment

Deploy to Vercel: deeplx-vercel

Features

Free: No API key required
Self-hosted: Full control
DeepL Quality: Same translation engine

Reverse-engineered API. May break with DeepL updates.

Caiyun (彩云小译)

Overview

Chinese translation service. Good for Chinese ↔ Japanese/English.

Setup

Get token from Caiyun Dashboard
Configure:

translator = CaiyunTranslator(
    lang_source='日本語',
    lang_target='简体中文',
    api_key='your-token'
)

Supported Languages

Chinese (Simplified)
Japanese
English

Features

Chinese-Optimized: Excellent for Chinese translation
Affordable: Competitive pricing

Papago

Overview

Naver’s translation service. Excellent for Korean.

Configuration

translator = PapagoTranslator(
    lang_source='日本語',
    lang_target='한국어'
)

Supported Languages

Korean, Japanese, Chinese
English, Spanish, French
Thai, Vietnamese, Indonesian

Features

Korean-Optimized: Best for Korean translation
Asian Languages: Good for Asian language pairs

Baidu Translate

Overview

Baidu’s translation service.

Configuration

translator = BaiduTranslator(
    api_key='your-api-key',
    secret_key='your-secret-key'
)

Features

Chinese Service: Based in China
Multi-language: Broad support

Yandex Translate

Overview

Russian translation service.

Configuration

translator = YandexTranslator(
    api_key='your-api-key'
)

Features

Russian-Optimized: Excellent for Russian
Multi-language: European language focus

Youdao Translate

Overview

Chinese translation service by Youdao (有道翻译).

Setup

Get API credentials from Youdao AI
Configure in settings:

from modules.translators import YoudaoTranslator

translator = YoudaoTranslator(
    lang_source='日本語',
    lang_target='简体中文',
    api_key='your-app-id',
    app_secret='your-app-secret'
)

Parameters

Parameter	Type	Default	Description
`api_key`	string	-	Youdao App ID (required)
`app_secret`	string	-	Youdao App Secret (required)

Supported Languages

Chinese (Simplified/Traditional)
Japanese, Korean
English, French, German, Spanish, Italian
Portuguese, Russian, Arabic, Vietnamese

Features

Chinese-Optimized: Excellent for Chinese translations
Multi-language: Supports many Asian and European languages
Affordable: Competitive pricing

Text Generation WebUI (TGW)

Overview

Connect to local text-generation-webui server for LLM-based translation.

Setup

Install and run text-generation-webui
Load your preferred translation model
Configure server URL in BallonTranslator

from modules.translators import TGWTranslator

translator = TGWTranslator(
    lang_source='日本語',
    lang_target='简体中文',
    app_url='http://127.0.0.1:5000',
    timeout=30
)

Parameters

Parameter	Type	Default	Description
`app_url`	string	-	TGW server URL (required)
`timeout`	int	30	Request timeout in seconds
`number_of_contexts`	int	3	Number of previous translations for context
`system_prompt`	text	(default)	System instruction for the model
`prompt`	text	(default)	Translation instruction template
`max_tokens`	int	200	Maximum output length
`temperature`	float	0.6	Sampling temperature
`top_p`	float	0.9	Nucleus sampling parameter
`top_k`	int	20	Top-K sampling parameter

Features

Local Control: Run any LLM locally
Customizable: Full control over prompts and parameters
Context-Aware: Uses translation history for consistency
Free: No API costs, just hardware

Use Cases

Testing different translation models
Using uncensored/specialized models
Offline translation with custom models
Fine-tuned models for specific domains

Offline Translation Models

Sugoi Translator (Japanese → English)

Overview

Offline Japanese to English translation model by mingshiba.

Only supports Japanese → English translation.

Setup

Download offline model from Google Drive
Extract sugoi_translator folder
Move to BallonsTranslator/ballontranslator/data/models/

Configuration

from modules.translators import SugoiTranslator

translator = SugoiTranslator(
    lang_source='日本語',
    lang_target='English',
    device='cuda'
)

Parameters

Parameter	Type	Default	Description
`device`	selector	auto	Processing device (cuda/cpu)

Model Files

data/models/sugoi_translator/
data/models/sugoi_translator/spm.ja.nopretok.model (tokenizer)

Features

Offline: No internet required
Free: No API costs
Privacy: All processing local
Japanese Focus: Optimized for manga/anime

Limitations

Japanese → English only
Requires significant disk space
GPU recommended for speed

ezTrans (Windows Only)

Overview

Windows-only offline translator for Japanese ↔ Korean translation.

Only available on Windows. Requires 32-bit translation engine files.

Setup

Download ezTrans engine files
Place engine files in the appropriate directory
Configure engine path in settings

Configuration

from modules.translators import ezTransTranslator

translator = ezTransTranslator(
    lang_source='日本語',
    lang_target='한국어',
    engine_path='path/to/ezTransXP.exe',
    engine_type='J2K',  # or 'K2J'
    dat_path='path/to/J2KEngine.dat'
)

Parameters

Parameter	Type	Default	Description
`engine_path`	string	-	Path to ezTrans engine executable
`engine_type`	selector	J2K	Translation direction (J2K or K2J)
`dat_path`	string	-	Path to engine data file

Supported Languages

Japanese ↔ Korean only

Features

Offline: No internet required
Bidirectional: Japanese ↔ Korean
Specialized: Optimized for J-K translation pairs

Limitations

Windows Only: Requires 32-bit Windows or compatibility layer
Limited Languages: Only Japanese and Korean
Setup Required: Needs external engine files

Sakura-13B-Galgame (Japanese → Chinese)

Overview

Sakura-13B-Galgame - LLM optimized for Japanese visual novel translation.

Setup

Download model from HuggingFace and configure path.

Configuration

from modules.translators import SakuraTranslator

translator = SakuraTranslator(
    lang_source='日本語',
    lang_target='简体中文',
    model_path='path/to/sakura-13b',
    low_vram_mode=True  # For GPUs with < 24GB VRAM
)

Parameters

Parameter	Type	Default	Description
`model_path`	string	-	Path to Sakura model
`low_vram_mode`	checkbox	True	Enable for < 24GB VRAM
`device`	selector	auto	Processing device
`dict_path`	string	-	Optional dictionary path
`version`	selector	0.9	Model version (0.9/1.0)
`temperature`	float	0.1	Sampling temperature
`top_p`	float	0.3	Nucleus sampling
`max_tokens`	int	512	Max output length

Dictionary Support

Sakura supports custom dictionaries:

# Load custom terminology
translator.params['dict_path'] = 'path/to/galtransl_dict.txt'

Dictionary formats:

Galtransl: Standard format
Sakura: Native format
JSON: Custom JSON format

Features

Offline: Local LLM
Context-Aware: Uses conversation context
Dictionary Support: Custom terminology
VN-Optimized: Trained on visual novels
VRAM Efficient: Low VRAM mode available

System Requirements

Minimum: 16GB RAM, 8GB VRAM (int4)
Recommended: 32GB RAM, 24GB VRAM (fp16)
Storage: ~26GB for model files

M2M100 (Multi-language)

Overview

Facebook’s multilingual translation model.

Setup

Download m2m100-1.2B-ctranslate2
Move to data/models/m2m100-1.2B-ctranslate2/

Configuration

translator = M2M100Translator(
    lang_source='ja',
    lang_target='en',
    device='cuda'
)

Features

100+ Languages: Massive language support
Offline: No internet needed
Single Model: One model for all pairs

See discussion #515 for more offline models.

LLM-based Translators

ChatGPT / GPT-4

Overview

OpenAI’s GPT models for high-quality translation.

Configuration

from modules.translators import GPTTranslator

translator = GPTTranslator(
    lang_source='日本語',
    lang_target='English',
    api_key='your-openai-api-key',
    model='gpt-4o'
)

Parameters

Parameter	Type	Default	Description
`api key`	string	-	OpenAI API key
`model`	selector	gpt-4o	Model (gpt-4o/gpt-4-turbo/gpt-3.5-turbo)
`override model`	string	-	Custom model name
`prompt template`	editor	-	Custom prompt
`chat system template`	editor	-	System message
`chat sample`	editor	-	Few-shot examples
`max tokens`	int	4096	Max response length
`temperature`	float	0.5	Sampling temperature
`top p`	float	1.0	Nucleus sampling
`delay`	float	0.3	Request delay
`max requests per minute`	int	20	Rate limiting
`retry attempts`	int	5	Retry on failure
`3rd party api url`	string	-	Custom API endpoint

Customizing Prompts

prompt = '''
You are translating a manga. 
Translate the following from {from_lang} to {to_lang}.
Keep the tone casual and natural.
'''

translator.params['prompt template']['value'] = prompt

Few-shot Learning

Provide examples for better translation:

samples = '''
日本語-English:
    source:
        - おはよう
        - 行ってきます  
    target:
        - Good morning
        - I'm heading out
'''

translator.params['chat sample']['value'] = samples

Features

High Quality: Best-in-class translation
Context-Aware: Understands manga context
Customizable: Full prompt control
Multi-language: Supports all major languages

Cost Considerations

GPT-4o: ~$5/1M input tokens
GPT-4-turbo: ~$10/1M input tokens
GPT-3.5-turbo: ~$0.50/1M input tokens

ChatGPT Experimental (Long Text)

Overview

Enhanced ChatGPT translator for long text with “jailbreak” prompt.

Configuration

translator = GPTTranslatorExp(
    api_key='your-key',
    model='gpt-4o'
)

Differences from Standard ChatGPT

Higher Token Usage: More detailed prompts
Better Stability: Improved sentence splitting
Long Text: Handles longer passages
Jailbreak Prompt: Enhanced translation quality

When to Use

Long text passages
Need maximum quality
Token cost is not a concern

OpenAI-Compatible APIs

Overview

Use any OpenAI-compatible API (local models, third-party services).

Supported Services

OpenRouter: Access multiple models
Together AI: Fast inference
Groq: Ultra-fast LLM inference
LocalAI: Run models locally
Ollama: Local model serving
LM Studio: Local LLM GUI

Configuration

# Using OpenRouter
translator = GPTTranslator(
    api_key='your-openrouter-key',
    model='anthropic/claude-3-opus',
    params={
        '3rd party api url': 'https://openrouter.ai/api/v1'
    }
)

# Using local Ollama
translator = GPTTranslator(
    api_key='dummy',  # Not used
    model='llama3',
    params={
        '3rd party api url': 'http://localhost:11434/v1'
    }
)

Features

Flexible: Use any OpenAI-compatible API
Local Options: Run models locally
Cost Control: Choose cheaper alternatives
Privacy: Keep data local

LLM API (Generic)

Overview

Generic LLM API translator for various services.

Configuration

translator = LLMAPITranslator(
    api_key='your-key',
    api_url='https://api.service.com/v1/chat/completions',
    model='model-name'
)

Features

Generic: Works with most LLM APIs
Customizable: Full control over requests

Utility Translators

None (Keep Existing)

Overview

Skip translation and keep existing translation field.

translator = TransNone(
    lang_source='日本語',
    lang_target='English'
)

Use Cases

Re-rendering without re-translating
Testing with pre-translated text
Manual translation workflow

Copy Source

Overview

Copy source text to translation field.

translator = TransSource(
    lang_source='日本語',
    lang_target='日本語'
)

Use Cases

Testing detection/inpainting only
Creating bilingual output
Debugging workflows

Usage Examples

Basic Translation

from modules.translators import TRANSLATORS

# Get translator
trans_class = TRANSLATORS.module_dict['google']
translator = trans_class(
    lang_source='日本語',
    lang_target='English'
)

# Translate text
text = "こんにちは、世界！"
translation = translator.translate(text)
print(translation)  # "Hello, world!"

Translate Text Blocks

# After detection and OCR
for blk in text_blocks:
    print(f"Original: {blk.text}")

translator.translate_textblk_lst(text_blocks)

for blk in text_blocks:
    print(f"Translated: {blk.translation}")

Batch Translation

# Translate multiple texts
texts = ["こんにちは", "ありがとう", "さようなら"]
translations = translator.translate(texts)

for src, tgt in zip(texts, translations):
    print(f"{src} -> {tgt}")

Choosing a Translator

Use Case	Recommended	Notes
Best quality	GPT-4 or DeepL	Highest accuracy
Free online	Google Translate	No API key needed
Offline	Sugoi or M2M100	No internet required
Japanese → English	Sugoi or GPT-4	Excellent for manga
Japanese → Chinese	Sakura-13B	VN-optimized
Multi-language	Google or M2M100	Broad support
Privacy-focused	Offline models	Data stays local
Budget-friendly	Google or DeepLX	Free options

Advanced Configuration

Rate Limiting

translator.params['delay'] = 0.5  # Wait 0.5s between requests
translator.params['max requests per minute'] = 20

Custom Text Processing

def preprocess_hook(translations, textblocks, translator, source_text):
    # Modify text before translation
    for i, text in enumerate(source_text):
        source_text[i] = text.upper()

translator._preprocess_hooks['custom'] = preprocess_hook

Post-processing

def postprocess_hook(translations, textblocks, translator):
    # Modify translations after translation
    for i, text in enumerate(translations):
        translations[i] = text.replace('...', '…')

translator._postprocess_hooks['custom'] = postprocess_hook

Adding Custom Translators

See 加别的翻译器.md for guide.

from modules.translators import BaseTranslator, register_translator

@register_translator('MyTranslator')
class MyTranslator(BaseTranslator):
    
    params = {
        'api_key': '',
        'delay': 0.0
    }
    
    def _setup_translator(self):
        self.lang_map['日本語'] = 'ja'
        self.lang_map['English'] = 'en'
    
    def _translate(self, src_list: List[str]) -> List[str]:
        # Your translation logic
        return [my_translate_func(text) for text in src_list]

Troubleshooting

API Key Errors

Verify API key is correct
Check API key has credits/quota
Ensure API key has proper permissions

Rate Limiting

# Increase delay
translator.params['delay'] = 1.0

# Reduce request rate
translator.params['max requests per minute'] = 10

Poor Translation Quality

Try better model: Use GPT-4 or DeepL
Provide context: Use context parameter
Add examples: Use few-shot learning
Customize prompt: Adjust instructions

Connection Errors

Check internet connection
Verify API endpoint URL
Try different region/VPN (for blocked services)
Use offline model as fallback

Get Started

Core Features

Modules

Advanced

​Online Translation Services

​Overview

​Configuration

​Parameters

​Supported Languages

​Features

​Overview

​Setup

​Parameters

​Formality Support

​Context Feature

​Supported Languages

​Features

​Overview

​Setup Options

​Self-hosted DeepLX

​Vercel Deployment

​Features

​Overview

​Setup

​Supported Languages

​Features

​Overview

​Configuration

​Supported Languages

​Features

​Overview

​Configuration

​Features

​Overview

​Configuration

​Features

​Overview

​Setup

​Parameters

​Supported Languages

​Features

​Overview

​Setup

​Parameters

​Features

​Use Cases

​Offline Translation Models

​Overview

​Setup

​Configuration

​Parameters

​Model Files

​Features

​Limitations

​Overview

​Setup

​Configuration

​Parameters

​Supported Languages

​Features

​Limitations

​Overview

​Setup

​Configuration

​Parameters

​Dictionary Support

​Features

​System Requirements

​Overview

​Setup

​Configuration

​Features

​LLM-based Translators

​Overview

​Configuration

​Parameters

​Customizing Prompts

​Few-shot Learning

​Features

​Cost Considerations

Online Translation Services

Overview

Configuration

Parameters

Supported Languages

Features

Overview

Setup

Parameters

Formality Support

Context Feature

Supported Languages

Features

Overview

Setup Options

Self-hosted DeepLX

Vercel Deployment

Features

Overview

Setup

Supported Languages

Features

Overview

Configuration

Supported Languages

Features

Overview

Configuration

Features

Overview

Configuration

Features

Overview

Setup

Parameters

Supported Languages

Features

Overview

Setup

Parameters

Features

Use Cases

Offline Translation Models

Overview

Setup

Configuration

Parameters

Model Files

Features

Limitations

Overview

Setup

Configuration

Parameters

Supported Languages

Features

Limitations

Overview

Setup

Configuration

Parameters

Dictionary Support

Features

System Requirements

Overview

Setup

Configuration

Features

LLM-based Translators

Overview

Configuration

Parameters

Customizing Prompts

Few-shot Learning

Features

Cost Considerations

Overview

Configuration

Differences from Standard ChatGPT

When to Use