Quick Start

Translate your first comic in under 5 minutes with this step-by-step guide.

Quick Start Guide

This guide will walk you through translating your first comic or manga with BallonTranslator. By the end, you’ll have a fully translated page ready to view.

Before you begin: Make sure you’ve completed the installation and have BallonTranslator running.

Your First Translation

1. Launch the Application

   Run BallonTranslator from your terminal or command prompt:

   # From source:
   python launch.py
   
   # Or on Windows with pre-packaged version:
   # Double-click launch_win.bat
   

   Always run from a terminal/command prompt so you can see progress messages and any errors that occur.

2. Configure Language Settings

   On first launch, configure your translation settings:

   1. Click the Settings icon (⚙️) in the toolbar
   2. Under Translation, select:
      • Source Language: The language of the original comic (e.g., Japanese, English)
      • Target Language: The language you want to translate to (e.g., English, Chinese)
   3. Choose a Translator from the dropdown:
      • For online: Google Translate (free, no setup)
      • For offline: m2m100 (requires model download)
      • For best quality: DeepL (requires API key)

   

   4. Click Save or Apply
3. Open Your Comic Folder

   Click the Folder icon (📁) in the toolbar and select a folder containing comic/manga images.

   # Your folder structure should look like:
   my-comic/
   ├── page_001.jpg
   ├── page_002.jpg
   ├── page_003.jpg
   └── ...
   

   Supported image formats: JPG, PNG, WEBP, BMP, and more. The application will load all images in the folder.

4. Run Automatic Translation

   1. Click the Run button in the toolbar
   2. Wait for the translation to complete

   

   What happens during translation?

   BallonTranslator processes the image through four stages:

   1. Text Detection: Locates all text regions in the image
   2. OCR: Recognizes and extracts the text
   3. Inpainting: Removes the original text from the image
   4. Translation & Rendering: Translates and renders new text with matched formatting

   Progress is shown in the terminal and status bar.

   First-time processing may take a few minutes as models are loaded into memory. Subsequent pages will be faster.

5. Review and Edit Results

   After translation completes:

   1. Review the translated text on the image
   2. Use A/D keys or Page Up/Down to navigate between pages
   3. Click any text block to edit it
   4. Adjust formatting using the right-side panel

   The translated page is automatically saved!

Navigation and Basic Controls

Master these essential shortcuts to work efficiently:

Page Navigation

A or Page Up     # Previous page
D or Page Down   # Next page

Viewing

Ctrl + +         # Zoom in
Ctrl + -         # Zoom out
Scroll Wheel     # Zoom in/out
0-9             # Adjust text layer opacity (0=transparent, 9=opaque)

Editing Modes

T               # Switch to Text Editing mode
P               # Switch to Image Editing mode (inpainting)
W               # Create new text block (drag with right mouse button)

Undo/Redo

Ctrl + Z        # Undo
Ctrl + Shift + Z # Redo (or Ctrl + Y)

The undo stack clears when you change pages. Make sure you’re happy with edits before navigating away.

Editing Text

After automatic translation, you’ll often want to refine the results.

Basic Text Editing

1. Select Text Block

   Press T to enter Text Editing mode, then click any text block to select it.

   Use Alt + Arrow Keys or Alt + WASD to quickly switch between text blocks without using the mouse.

2. Edit the Text

   The text editor appears on the right side. Simply type to change the translation.

   
3. Format the Text

   Use the formatting panel to adjust:

   • Font: Choose from system fonts
   • Size: Adjust text size
   • Color: Change text color
   • Bold/Italic/Underline: Apply text styles
   • Alignment: Left, center, right, or justified

   Keyboard shortcuts for formatting:

   Ctrl + B    # Bold
   Ctrl + I    # Italic
   Ctrl + U    # Underline
   
4. Apply Effects

   In the Effects section:

   • Add shadows for better readability
   • Adjust transparency
   • Add outlines (stroke)

Creating New Text Blocks

To add translation for text the auto-detection missed:

1. Press W to activate text block creation mode
2. Right-click and drag on the canvas to draw a text box
3. Type your translation
4. Format as needed

Batch Editing

Edit multiple text blocks at once:

1. Press Ctrl + A to select all text blocks
2. Or Shift + Click to select multiple blocks
3. Change formatting in the panel - it applies to all selected blocks

Image Editing (Inpainting)

Sometimes automatic text removal isn’t perfect. You can manually fix it:

Using the Inpainting Brush

1. Enter Image Editing Mode

   Press P to switch to image editing mode.

2. Paint Over Text

   • Left-click and drag to mark areas that need inpainting
   • Right-click and drag to erase inpainting marks
3. Apply Inpainting

   • Press Spacebar or click Inpaint button
   • The algorithm fills in the marked areas with reconstructed background

   
4. Adjust Transparency

   Use the slider in the bottom-right to adjust original image transparency and see your edits clearly.

Using the Rectangle Tool

For faster text removal on simple backgrounds:

1. Select Rectangle Tool in the toolbar
2. Left-click and drag to draw a rectangle over text
3. Release to automatically remove text (if “Auto” is checked)
4. Try Method 1 or Method 2 for different results
5. Right-click and drag to erase inpainting results

Draw the rectangle slightly larger than the text for best results. Both methods work differently - experiment to see which works better for your image.

Search and Replace

Find and fix translation mistakes across multiple pages:

Search in Current Page

Ctrl + F    # Open search in current page

Global Search

Ctrl + G    # Search across all pages in project

The search dialog supports:

• Find text in original or translation
• Replace single occurrence
• Replace all occurrences
• Case-sensitive search

Exporting Your Work

Save Individual Images

Translated images are automatically saved to your project folder:

my-comic/
├── page_001.jpg           # Original
├── page_001_translated.jpg # Translated version
├── page_001.json          # Translation data
└── ...

Export to Word Document

For collaboration or review:

1. Go to File → Export → Word Document
2. Share the document with translators
3. Import it back: File → Import → Word Document

Advanced: Settings Panel

Fine-tune the automatic translation process:

Text Detection Settings

• Model: Choose detection model (default works for most manga/comics)
• Threshold: Adjust sensitivity (lower = detects more, higher = more selective)

OCR Settings

• OCR Model: Choose recognition model based on source language
• Enable Font Detection: Automatically detect original fonts (experimental)

Inpainting Settings

• Method: Choose inpainting algorithm (AOT, LaMa, PatchMatch)
• Device: CPU or CUDA (GPU)

Translation Settings

• Translator: Select translation service
• API Keys: Configure for services like DeepL, OpenAI

Typesetting Settings

Control how translated text is rendered:

• Font Size: “Decide by program” (automatic) or “Use global setting”
• Font Color: “Decide by program” (matches original) or “Use global setting”
• Alignment: “Decide by program” or “Use global setting”

Global settings are the formats shown in the right panel when no text block is selected.

Tips for Best Results

Improve translation quality

1. Use better translators: DeepL or GPT-4 produce more natural translations than Google
2. Review and edit: Always review machine translations - they’re not perfect
3. Understand context: Manual editing for idioms and cultural references improves quality

Speed up processing

1. Enable GPU: Make sure CUDA/ROCm is properly configured
2. Load models on demand: Enable in settings to reduce memory usage
3. Batch process: Use headless mode for processing many files:

python launch.py --headless --exec_dirs "/path/to/comic1,/path/to/comic2"

Handle difficult pages

1. Vertical text: Japanese vertical text (tategaki) may need manual adjustment
2. Stylized fonts: Very decorative text may not be detected well
3. Complex backgrounds: Use multiple inpainting attempts with different methods
4. Small text: Increase detection sensitivity in settings

Organize your workflow

1. Use projects: Keep each manga/comic in its own folder
2. Save frequently: Changes are auto-saved when changing pages
3. Export to Word: Great for team collaboration and quality checking
4. Keep originals: The original images are never modified

Headless Mode (Batch Processing)

Process multiple comics without the GUI:

# Process one or more directories:
python launch.py --headless --exec_dirs "/path/to/comic1,/path/to/comic2"

# Continuous mode (prompts for new directories):
python launch.py --headless_continuous

Configuration is loaded from config/config.json. Set up your preferred settings in the GUI first, then use headless mode.

Specify Logical DPI

If text sizes render incorrectly:

python launch.py --headless --exec_dirs "/path/to/comic" --ldpi 96
# Common values: 96 (Windows), 72 (macOS)

Troubleshooting Common Issues

Text not detected

Possible causes:

• Text is too small or stylized
• Wrong detection model for the language
• Detection threshold too high

Solutions:

1. Lower detection threshold in settings
2. Try different detection models
3. Manually create text blocks with W key

Translation is wrong or nonsensical

Solutions:

1. Check OCR accuracy - click text blocks to see recognized text
2. Fix OCR errors manually, then re-translate
3. Try a different translator
4. Manually edit the translation

Text formatting looks wrong

Solutions:

1. Check typesetting settings - switch to “Use global setting”
2. Manually adjust font, size, and colors
3. For vertical text: May need manual layout adjustment

Inpainting leaves artifacts

Solutions:

1. Try different inpainting methods (Method 1 vs Method 2)
2. Draw larger rectangles around text
3. Use the inpainting brush for fine details
4. Multiple passes may help on complex backgrounds

Application runs slowly

Check:

1. Is GPU acceleration enabled? (see Installation)
2. Are other GPU apps running?
3. Enable “Load models on demand” in settings

Next Steps

Now that you’ve completed your first translation, explore more advanced features:

Text Detection

Learn about text detection models and configuration

Text Editing

Master advanced text formatting and editing techniques

Image Editing

Deep dive into inpainting tools and techniques

Configuration

Optimize settings for your specific use case

Getting Help

If you encounter issues:

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share tips
• Debug Mode: Run with --debug flag for detailed error messages

python launch.py --debug

When reporting issues, always include:

• Your OS and Python version
• The error message from the terminal
• Steps to reproduce the problem