Localization - BuxarTranslate Documentation

File: localization.html
Purpose: Localization guide and adding new languages

🌐 Supported Interface Languages

🇺🇸 English en

Default language, full support

🇷🇺 Russian ru

Full interface localization

🇩🇪 Deutsch de

German interface language

🇪🇸 Spanish es

Spanish interface language

🇫🇷 French fr

French interface language

🇮🇹 Italian it

Italian interface language

📁 Localization Structure

Localization is organized according to WebExtensions standard in _locales folder:

_locales/
├── en/
│   └── messages.json    # English translations
├── ru/
│   └── messages.json    # Russian translations  
├── de/
│   └── messages.json    # German translations
├── es/
│   └── messages.json    # Spanish translations
├── it/
│   └── messages.json    # Italian translations
└── fr/
    └── messages.json    # French translations
            

📝 Translation File Format

Each messages.json file contains object with translation keys:

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Extension name"
  },
  "extensionDescription": {
    "message": "Translate selected text in emails with one click",
    "description": "Extension description"
  },
  "translateTo": {
    "message": "Translate to $1",
    "description": "Context menu item"
  },
  "selectTextRightClick": {
    "message": "Select text → Right-click → Translate",
    "description": "Popup instruction"
  }
}
            

🔧 Adding New Language

1. Create language folder

Create folder with language code in _locales/ directory

mkdir _locales/ja # for Japanese language

2. Create messages.json file

Create translation file in new folder

touch _locales/ja/messages.json

3. Add translations

Copy structure from English file and translate all values

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Extension name"
  },
  "translateTo": {
    "message": "Translate to $1",
    "description": "Context menu item"
  }
}
                

4. Update language scanning

Add language code to scanAvailableLanguages() function in popup.js

// In popup.js file
const possibleLangs = ['en', 'ru', 'es', 'de', 'fr', 'it', 'ja', 'zh', 'ko'];
// Add your language to possibleLangs array
                

5. Test translation

Install extension and test new language operation

🔄 Dynamic Translation Loading

System dynamically loads translations for selected language:

// Loading translations for specific language
async function loadTranslations(lang) {
  try {
    const response = await fetch(`_locales/${lang}/messages.json`);
    if (response.ok) {
      return await response.json();
    }
  } catch (error) {
    console.error(`Error loading translations for ${lang}:`, error);
  }
  return null;
}

// Language manager
const LanguageManager = {
  async init() {
    const storage = await browser.storage.local.get('userLang');
    const userLang = storage.userLang || 'auto';
    
    // Determine interface language
    if (userLang === 'auto') {
      const uiLang = browser.i18n.getUILanguage();
      this.currentLang = uiLang.split('-')[0];
    } else {
      this.currentLang = userLang;
    }
    
    // Load translations
    this.translations = await loadTranslations(this.currentLang) || {};
  }
};
            

🎯 Key Translation Elements

Mandatory translation keys:

extensionName - extension name
extensionDescription - extension description
translateTo - context menu item
selectTextRightClick - usage instruction
targetLanguage - language selection header
saveSettings - save settings button
originalText - original text header
translatedText - translated text header

Placeholders in translations:

// Example of placeholder usage
"translateTo": {
  "message": "Translate to $1",
  "description": "Context menu item"
}

// In code:
const menuTitle = browser.i18n.getMessage("translateTo", [targetLangName]);
            

🔍 Localization Testing

Automatic Detection

Set userLang: "auto" to test automatic language detection

Manual Selection

Use dropdown in settings to switch between languages

Check All Elements

Make sure all interface elements and messages are translated

Test Placeholders

Check correct replacement of $1, $2 etc. in translations

⚠️ Common Issues

Missing Keys

Solution: Make sure all keys from English version are present in translation

Incorrect Placeholders

Solution: Check correspondence of $1, $2 count in translation and code

File Encoding

Solution: Save JSON files in UTF-8 encoding

Syntax Errors

Solution: Check JSON validity using JSON validator

← Back: Technical Details Next: Troubleshooting →

🌍 BuxarTranslate Localization