Skip to main content

​
Configuration

BallonTranslator stores all settings in config/config.json. This file is automatically created on first run and updated whenever you change settings through the UI.

​
Configuration File Location

The default configuration file is located at: 
config/config.json
You can specify a custom config file path when launching: 
python launch.py --config_path /path/to/your/config.json

​
Configuration Structure

The configuration file is organized into several main sections:

​
Module Configuration

Controls the automation modules and their parameters: 
{
  "module": {
    "textdetector": "ctd",
    "ocr": "mit48px",
    "inpainter": "lama_large_512px",
    "translator": "google",
    "enable_detect": true,
    "enable_ocr": true,
    "enable_translate": true,
    "enable_inpaint": true,
    "translate_source": "日本語",
    "translate_target": "简体中文",
    "load_model_on_demand": false,
    "empty_runcache": false
  }
}

​
Module Settings

SettingTypeDescription
textdetectorstringText detection model (e.g., “ctd”, “YSGDetector”)
ocrstringOCR model (e.g., “mit48px”, “manga_ocr”)
inpainterstringInpainting model (e.g., “lama_large_512px”, “aot”)
translatorstringTranslation service (e.g., “google”, “deepl”, “sakura”)
enable_detectbooleanEnable text detection
enable_ocrbooleanEnable OCR
enable_translatebooleanEnable translation
enable_inpaintbooleanEnable inpainting
keep_exist_textlinesbooleanKeep existing text lines during detection
ocr_font_detectbooleanEnable font detection during OCR
translate_sourcestringSource language
translate_targetstringTarget language
check_need_inpaintbooleanCheck if inpainting is needed
load_model_on_demandbooleanLoad models only when needed (saves memory)
empty_runcachebooleanClear run cache after processing

​
Module Parameters

Each module can have additional parameters: 
{
  "module": {
    "textdetector_params": {},
    "ocr_params": {},
    "translator_params": {
      "google": {
        "delay": 0.0
      },
      "deepl": {
        "api_key": "your-api-key"
      }
    },
    "inpainter_params": {}
  }
}

​
Drawing Panel Configuration

Settings for the image editing tools: 
{
  "drawpanel": {
    "pentool_color": [0, 0, 0],
    "pentool_width": 30.0,
    "pentool_shape": 0,
    "inpainter_width": 30.0,
    "inpainter_shape": 0,
    "current_tool": 0,
    "rectool_auto": false,
    "rectool_method": 0,
    "recttool_dilate_ksize": 0
  }
}

​
Global Font Format

Default font formatting for rendered text: 
{
  "global_fontformat": {
    "size": 20,
    "family": "Arial",
    "bold": false,
    "italic": false,
    "underline": false,
    "color": [0, 0, 0],
    "alignment": "center"
  }
}

​
UI Settings

Interface and display preferences: 
{
  "show_page_list": false,
  "imgtrans_paintmode": false,
  "imgtrans_textedit": true,
  "imgtrans_textblock": true,
  "mask_transparency": 0.0,
  "original_transparency": 0.0,
  "open_recent_on_startup": true,
  "darkmode": false,
  "display_lang": "English",
  "textselect_mini_menu": true,
  "fold_textarea": false,
  "show_source_text": true,
  "show_trans_text": true
}

​
Layout and Lettering Flags

Control automatic text formatting: 
{
  "let_fntsize_flag": 0,
  "let_fntstroke_flag": 0,
  "let_fntcolor_flag": 0,
  "let_fnt_scolor_flag": 0,
  "let_fnteffect_flag": 1,
  "let_alignment_flag": 0,
  "let_writing_mode_flag": 0,
  "let_family_flag": 0,
  "let_autolayout_flag": true,
  "let_uppercase_flag": true
}
These flags determine whether the program decides formatting automatically (value 0) or uses global settings (value 1).

​
Search Settings

{
  "fsearch_case": false,
  "fsearch_whole_word": false,
  "fsearch_regex": false,
  "fsearch_range": 0,
  "gsearch_case": false,
  "gsearch_whole_word": false,
  "gsearch_regex": false,
  "gsearch_range": 0,
  "search_url": "https://www.google.com/search?q="
}

​
Image Export Settings

{
  "imgsave_quality": 100,
  "imgsave_ext": ".png",
  "intermediate_imgsave_ext": ".png"
}

​
Editing Configuration

​
Through the UI

The easiest way to configure BallonTranslator is through the Settings Panel:
  1. Click the settings icon in the title bar
  2. Navigate through different tabs (Module, Drawing, Typesetting, etc.)
  3. Changes are automatically saved when you close the settings panel

​
Manual Editing

  1. Close BallonTranslator
  2. Open config/config.json in a text editor
  3. Make your changes
  4. Save the file
  5. Launch BallonTranslator
Invalid JSON syntax will cause the configuration to reset to defaults. Always backup your config file before manual editing.

​
Configuration for Headless Mode

When running in headless mode, all settings are loaded from the config file. Make sure to configure everything through the UI first, then use headless mode: 
python launch.py --headless --exec_dirs "/path/to/manga1,/path/to/manga2"
See the Headless Mode guide for more details.

​
Text Styles Configuration

Text style presets are stored separately in: 
config/textstyles/default.json
This file contains an array of font format presets that you can apply to text blocks: 
[
  {
    "name": "Title",
    "size": 32,
    "family": "Arial",
    "bold": true,
    "color": [0, 0, 0]
  },
  {
    "name": "Speech",
    "size": 20,
    "family": "Comic Sans MS",
    "color": [0, 0, 0]
  }
]

​
Translator-Specific Configuration

Different translators require different parameters. See examples below:

​
DeepL

"translator_params": {
  "deepl": {
    "api_key": "your-deepl-api-key"
  }
}

​
Caiyun

"translator_params": {
  "caiyun": {
    "token": "your-caiyun-token"
  }
}

​
OpenAI-compatible APIs

"translator_params": {
  "ChatGPT": {
    "api_key": "your-api-key",
    "api_base": "https://api.openai.com/v1",
    "model": "gpt-4"
  }
}

​
Sakura

"translator_params": {
  "Sakura-13B-Galgame": {
    "low_vram_mode": true
  }
}

​
Recent Projects List

The config file also stores your recent projects: 
{
  "recent_proj_list": [
    "/path/to/project1",
    "/path/to/project2"
  ]
}
This enables the “Open Recent” functionality.

​
Reset Configuration

To reset to default settings:
  1. Close BallonTranslator
  2. Delete or rename config/config.json
  3. Launch BallonTranslator (a new default config will be created)

​
Configuration Validation

BallonTranslator validates the configuration on load. If the config file is corrupted or contains invalid values:
  • A warning will be logged
  • The program will use default values for invalid settings
  • Your config file will be backed up as config.json.tmp

​
Environment Variables

Some settings can be overridden with environment variables:
VariableDescription
INDEX_URLPyPI index URL for package installation
TORCH_COMMANDCustom PyTorch installation command
GITPath to git executable
QT_APIQt API to use (set automatically)
BALLOONTRANS_DEBUGEnable debug mode (set by --debug flag)

​
Next Steps