Translation Guide

Want to help translate WhisperSubTranslate into a new language? This guide covers everything you need.

Current Languages

UI languages

Language	Code	Maintainer
Korean	ko	@Blue-B
English	en	@Blue-B
Japanese	ja	@Blue-B
Chinese	zh	@Blue-B
Polish	pl	@Blue-B

Translation targets

The app currently supports these 15 translation targets:

ko, en, ja, zh, es, fr, de, it, pt, ru, hu, ar, pl, tr, fa

Turkish (tr) is a translation target only. It does not provide a Turkish UI or a Turkish README yet.

How to Add a New UI Language

1. Add translation strings

Translatable strings are split per language as JSON, and the bundled locales/i18n.js is generated from them — do not edit locales/i18n.js by hand.

1. Copy locales/en.json to locales/<code>.json (e.g. locales/de.json) and translate every value.
2. If a string needs interpolation/pluralization (e.g. "Removed: ${name}"), it lives in locales/i18n.functions.js as a small arrow function — copy the en entry there for your language too.
3. Regenerate the bundled global the app loads:

npm run i18n:build      # writes locales/i18n.js from the JSON + functions
npm run i18n:check      # verifies i18n.js is in sync (also runs in `npm run check` / CI)

Translate online: You can also use Weblate, which edits the same locales/*.json files.

Important: Every key in locales/en.json and every helper in locales/i18n.functions.js must be present. Missing keys fall back to English.

2. Add LOG_I18N mappings (renderer.js)

In renderer.js, find the LOG_I18N object and add a mapping array for your language. This translates Korean log output into your language:

const LOG_I18N = {
  en: [ ... ],
  ja: [ ... ],
  zh: [ ... ],
  pl: [ ... ],
  // Add your language:
  xx: [
    { re: /자막 추출을 시작합니다/g, to: 'Starting subtitle extraction' },
    { re: /처리 중:/g, to: 'Processing:' },
    // ... add patterns for log messages
  ]
};

3. Add language selector option

In index.html, add an <option> to the language selector:

<select id="uiLangSelect">
  <option value="ko">한국어</option>
  <option value="en">English</option>
  <!-- Add your language -->
  <option value="xx">Your Language</option>
</select>

4. Add MODEL_I18N, LANG_NAMES_I18N entries (renderer.js)

In renderer.js, add your language to these objects:

• MODEL_I18N.xx — model descriptions
• LANG_NAMES_I18N.xx — language names in your language

5. (Optional) Add a README translation

Create README.xx.md following the same structure as README.md, and add a link to it in all existing READMEs.

6. Submit a Pull Request

• Branch: feature/i18n-add-<language>
• Include all modified files
• Test with npm start and switch the UI language to verify

How to Add a Translation Target Language

Translation target languages allow users to translate subtitles into that language.

1. Add display names (renderer.js)

In renderer.js, add the language code to every UI language block in LANG_NAMES_I18N:

const LANG_NAMES_I18N = {
  ko: { ..., xx: '새언어' },
  en: { ..., xx: 'New Language' },
  // ... for all UI languages
};

2. Add provider mappings

• In translator-enhanced.js, update mapToHumanLang().
• In translator-enhanced.js, update mapToDeepLLang() if DeepL supports the language.
• In local-translator.js, update LANGUAGE_NAMES for the bundled Hy-MT2 model.

3. Add to index.html

Add a checkbox to the targetLanguageList panel:

<div id="targetLanguageList">
  <!-- Add your language -->
  <label class="lang-check">
    <input type="checkbox" value="xx" /><span>New Language (xx)</span>
  </label>
</div>

4. Update docs and tests

• Add the code to the translation-target list in every README.
• Add smoke-test assertions for provider and human-readable mappings.
• Run npm run check before submitting.

Tips

• Use the en block as the source of truth — it has the most neutral phrasing
• Keep translations concise — UI space is limited
• Test all screens: main UI, settings modal, queue display, error messages
• Edit locales/*.json (+ i18n.functions.js for interpolated strings), then run npm run i18n:build
• Run npm run check before submitting (lint + i18n sync + tests)

Questions?

Open an issue with the label i18n if you need help.