Languages & dynamic translation¶

KorTTY supports eight built-in languages and can generate translations for any additional language via translation APIs, allowing you to use the interface in your preferred language.

Built-in Languages¶

KorTTY includes full translations for the following languages:

• English (default)
• German
• Italian
• Spanish
• Portuguese
• French
• Croatian
• Dutch

The application automatically detects your system language on first run and loads the matching translation if available. If your system language is not in the built-in list, English is used as a fallback.

Changing Language¶

To switch to a different built-in language:

1. Open Settings → Language
2. Select the desired language from the dropdown
3. Restart the application for the change to take effect

To automatically use your system language:

• Select Auto-detect (System Language) in Settings → Language
• The application will detect your system locale on startup

Dynamic Translation (Additional Languages)¶

You can generate language files for any language supported by a translation API. This allows KorTTY to display its interface in languages beyond the eight built-in options.

Translation Providers¶

KorTTY supports the following translation services:

Generating a Translation¶

To generate translations for a new language:

1. Open Settings → Translation
2. Choose a Translation API from the dropdown
3. Enter your API key if required (the key is stored encrypted with your master password)
4. Optionally set a custom API URL (for example, to point to a self-hosted LibreTranslate instance)
5. Click Test API Connection to verify the setup works
6. Select the target language from the language dropdown
7. Click Generate Language File

The generated language file is saved to ~/.kortty/i18n/messages_XX.properties, where XX is the two-letter language code. After generation, restart the application to make the new language available in Settings → Language.

After App Upgrades¶

When KorTTY is upgraded to a new version, previously generated language files are automatically detected as outdated if they were created with an older app version. In Settings → Translation, a notice appears indicating which languages need updating.

To refresh all outdated language files after an upgrade:

1. Open Settings → Translation
2. Click Regenerate outdated
3. All generated languages are re-translated to include new or changed keys from the new version

Regenerating is not urgent: until you do it, any string added after your file was generated falls back to the packaged translation for that language, or to English when the language ships no packaged file. You see a translated or English label, never a raw key name.

Storage and Persistence¶

• Generated language files are stored in ~/.kortty/i18n/
• Each file is a standard Java properties file (messages_XX.properties)
• Files persist across application restarts and updates
• Language files are included in encrypted backups created via Edit → Create Backup

How It Works¶

KorTTY's internationalization system is built around a resource bundle architecture:

• Base language: English strings are defined in i18n/messages.properties bundled with the application
• Built-in languages: Pre-translated properties files are packaged with the application
• Dynamic languages: Generated properties files are loaded from ~/.kortty/i18n/ on startup
• Placeholder preservation: Translation APIs preserve parameterized placeholders like {0}, {1}, and ${variable} during translation
• Lookup fallback: A file in ~/.kortty/i18n/ is consulted first, then the packaged file for the same language, then the English base bundle — so a key the generated file lacks still resolves

The LanguageManager class detects available locales from both built-in translations and dynamically generated files, allowing you to seamlessly mix both types.

Platform Locale Detection¶

KorTTY uses your operating system's locale settings as the default when auto-detect is enabled. The language detection works across platforms:

• macOS: Reads system language from System Preferences
• Windows: Uses Windows language settings
• Linux: Respects the LANG environment variable and system locale settings

If your system's primary language is not in the built-in or generated list, English is automatically selected.

Tips for Translation Quality¶

Troubleshooting¶