Internationalization

Internationalization

한국어

Guide to adding and contributing translations for ivLyrics.

---

Overview

ivLyrics supports 18 languages for its user interface:

Language	Code	File
English	en	LangEn.js
Korean	ko	LangKo.js
Japanese	ja	LangJa.js
Chinese (Simplified)	zh-CN	LangZhCN.js
Chinese (Traditional)	zh-TW	LangZhTW.js
Spanish	es	LangEs.js
French	fr	LangFr.js
German	de	LangDe.js
Italian	it	LangIt.js
Portuguese	pt	LangPt.js
Russian	ru	LangRu.js
Arabic	ar	LangAr.js
Persian	fa	LangFa.js
Hindi	hi	LangHi.js
Bengali	bn	LangBn.js
Thai	th	LangTh.js
Vietnamese	vi	LangVi.js
Indonesian	id	LangId.js

---

Language File Structure

Language files are located in the langs/ directory.

File Format

window.ivLyricsLangs = window.ivLyricsLangs || {};
window.ivLyricsLangs['en'] = {
    // Settings section
    settings: {
        title: 'Settings',
        save: 'Save',
        cancel: 'Cancel',
        // Subsections
        general: {
            title: 'General',
            language: 'Language'
        },
        display: {
            title: 'Display',
            fontSize: 'Font Size'
        }
    },

    // Buttons
    buttons: {
        ok: 'OK',
        cancel: 'Cancel',
        close: 'Close',
        apply: 'Apply'
    },

    // Messages and notifications
    notifications: {
        saved: 'Settings saved',
        error: 'An error occurred'
    },

    // AI Providers section
    aiProviders: {
        title: 'AI Providers',
        enable: 'Enable',
        apiKey: 'API Key'
    }
};

---

Using Translations

The _t() Function

Use the _t() function to get translated strings:

// Simple key
const text = _t('buttons.ok');  // Returns 'OK' for English

// Nested key
const title = _t('settings.general.title');

// With fallback
const custom = _t('custom.key.that.might.not.exist', 'Fallback Text');

In React Components

const MyComponent = () => {
    return React.createElement('button', null, _t('buttons.save'));
};

---

Adding a New Language

Step 1: Create Language File

Create a new file in langs/ (e.g., LangNl.js for Dutch):

window.ivLyricsLangs = window.ivLyricsLangs || {};
window.ivLyricsLangs['nl'] = {
    // Copy structure from LangEn.js and translate
    settings: {
        title: 'Instellingen',
        // ...
    }
};

Step 2: Update manifest.json

Add the file to the subfiles array:

{
    "subfiles": [
        "langs/LangNl.js"
    ]
}

Step 3: Register in I18n.js

Add the language to the available languages:

const AVAILABLE_LANGUAGES = {
    'en': 'English',
    'ko': '한국어',
    'nl': 'Nederlands',  // Add new language
    // ...
};

---

Translation Guidelines

General

1. Keep placeholders: Preserve any {variable} placeholders
2. Match length: Try to keep translations similar in length
3. Be consistent: Use the same term for the same concept
4. Use formal tone: Use polite/formal language where appropriate

Technical Terms

Some terms should remain in English or use common translations:

English	Recommendation
Spotify	Keep as is
API	Keep or use common abbreviation
Karaoke	Keep or use local equivalent
Sync	Translate if common translation exists

RTL Languages

For right-to-left languages (Arabic, Persian):

• The UI automatically adjusts for RTL
• Ensure text direction markers are used if needed

---

Testing Translations

1. Add or modify language file
2. Run spicetify apply
3. Open Spotify and go to Settings
4. Change language to test
5. Check all UI sections

---

Contributing Translations

Via GitHub

1. Fork the repository
2. Create/update language file
3. Test your changes
4. Submit a pull request

Translation Checklist

Before submitting:

• All keys from English file are translated
• No missing or extra keys
• Placeholders preserved
• Special characters properly escaped
• Tested in the app

---

Common Translation Keys

Essential Keys

{
    settings: { title, save, cancel },
    buttons: { ok, cancel, close, apply },
    notifications: { saved, error },
    menu: { settings, fullscreen, close },
    lyrics: { noLyrics, loading },
    translation: { translate, phonetic, furigana },
    providers: { title, enable, disable }
}

Complete Example

See langs/LangEn.js for the complete structure with all keys.

---

Related

• Contributing - General contribution guide
• Architecture Overview - Project structure