Skip to main content

Usage Guide (Quick Start)

This guide follows a practical step-by-step flow to help you complete first-time setup.

1. Install and Launch​

  1. Download and install Mask.
  2. On first launch, grant required system permissions (for example, Screen Recording).
  3. Open Settings and confirm the app version displays correctly.

If you want to understand what each permission is used for, see: Data & Privacy

2. Select a Model Provider and Add API Key​

  1. In Settings, choose the model provider you want to use.
  2. Paste the corresponding API key.
  3. If you use Claude, verify that your text model and VLM model match your cost and capability needs.
  4. Save and run a small test translation.

If you do not have a key yet, read API Key Setup first.

3. Start Translating​

  1. Select the screen region you want to translate.
  2. Wait for OCR and model processing.
  3. Check the overlay result. If needed, adjust the selection and retry.

If you mainly use Mask for visual novels, galgames, or ADV-style reading, and need more detail about window binding, dialogue-box regions, split choices, auto page-turn, or coordinate calibration, continue with: Visual Novel Guide

4. What Each "Region Settings" Button Does​

In Settings, the Region Settings section contains these buttons:

  • Focus: Select the target window Mask should bind to. In most cases, do this first so Mask only works on the current game or app window.
  • OCR Region: Define the area OCR should actually read. If you only want dialogue text, keep this box tight around the text area.
  • Dual Mask Regions: Define where translated overlay masks are displayed. If multi-region OCR or option recognition is enabled, set 1 dialogue mask + 1 option mask here.
  • Screen Change Detection Region: Limit the area used for screen-change detection. This helps avoid false triggers from character sprites, effects, or animations outside the dialogue box.
  • Click Detection Region: Limit the area checked after a global click trigger. Useful when you only want clicks in the dialogue / page-turn area to trigger new-text detection.
  • Auto Page-Turn Region: Set the actual click target used for automatic page turning. Usually this should match the game's next-line / next-page hotspot. This button only appears when the current environment supports auto page-turn injection. The Mac App Store version does not support auto page-turn at this time.
  • Coordinate Calibration: Correct click/selection coordinate offsets. This is mainly useful in CrossOver or Whisky environments where coordinates may not line up exactly.

Recommended order: use Focus first, then set OCR Region, then add Dual Mask Regions, detection regions, and the auto page-turn region as needed.

5. Practical Tips for Better Quality​

  • For dense text, segment-by-segment translation is usually more stable.
  • Keeping nearby context improves coherence significantly.
  • For small fonts, zoom in first to reduce OCR misses.

6. Recommendations by Scenario​

Comics / Game Dialogues​

  • Focus on one dialogue box per selection.
  • Avoid selecting portraits, visual effects, and decorative text together.

Document / Web Reading​

  • Translate paragraphs in semantic chunks.
  • For terminology-heavy content, reuse the same model for consistency.

7. Daily Maintenance Tips​

  • Keep Mask updated to the latest version.
  • If you switch providers, verify key permissions and quota.
  • For errors, run a minimal test (single sentence, small region) first for faster diagnosis.

8. Next Steps​