Локализация - BuxarTranslate Документация

Файл: localization.html
Назначение: Руководство по локализации и добавлению новых языков

🌐 Поддерживаемые языки интерфейса

🇺🇸 English en

Язык по умолчанию, полная поддержка

🇷🇺 Русский ru

Полная локализация интерфейса

🇩🇪 Deutsch de

Немецкий язык интерфейса

🇪🇸 Español es

Испанский язык интерфейса

🇫🇷 Français fr

Французский язык интерфейса

🇮🇹 Italiano it

Итальянский язык интерфейса

📁 Структура локализации

Локализация организована по стандарту WebExtensions в папке _locales:

_locales/
├── en/
│   └── messages.json    # Английские переводы
├── ru/
│   └── messages.json    # Русские переводы  
├── de/
│   └── messages.json    # Немецкие переводы
├── es/
│   └── messages.json    # Испанские переводы
├── it/
│   └── messages.json    # Итальянские переводы
└── fr/
    └── messages.json    # Французские переводы
            

📝 Формат файлов перевода

Каждый файл messages.json содержит объект с ключами перевода:

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Название расширения"
  },
  "extensionDescription": {
    "message": "Translate selected text in emails with one click",
    "description": "Описание расширения"
  },
  "translateTo": {
    "message": "Translate to $1",
    "description": "Пункт контекстного меню"
  },
  "selectTextRightClick": {
    "message": "Select text → Right-click → Translate",
    "description": "Инструкция в popup"
  }
}
            

🔧 Добавление нового языка

1. Создайте папку для языка

Создайте папку с кодом языка в директории _locales/

mkdir _locales/ja # для японского языка

2. Создайте файл messages.json

Создайте файл перевода в новой папке

touch _locales/ja/messages.json

3. Добавьте переводы

Скопируйте структуру из английского файла и переведите все значения

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Название расширения"
  },
  "translateTo": {
    "message": "Перевести на $1",
    "description": "Пункт контекстного меню"
  }
}
                

4. Обновите сканирование языков

Добавьте код языка в функцию scanAvailableLanguages() в popup.js

// В файле popup.js
const possibleLangs = ['en', 'ru', 'es', 'de', 'fr', 'it', 'ja', 'zh', 'ko'];
// Добавьте ваш язык в массив possibleLangs
                

5. Протестируйте перевод

Установите расширение и проверьте работу нового языка

🔄 Динамическая загрузка переводов

Система динамически загружает переводы для выбранного языка:

// Загрузка переводов для конкретного языка
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;
}

// Менеджер языка
const LanguageManager = {
  async init() {
    const storage = await browser.storage.local.get('userLang');
    const userLang = storage.userLang || 'auto';
    
    // Определяем язык интерфейса
    if (userLang === 'auto') {
      const uiLang = browser.i18n.getUILanguage();
      this.currentLang = uiLang.split('-')[0];
    } else {
      this.currentLang = userLang;
    }
    
    // Загружаем переводы
    this.translations = await loadTranslations(this.currentLang) || {};
  }
};
            

🎯 Ключевые элементы перевода

Обязательные для перевода ключи:

extensionName - название расширения
extensionDescription - описание расширения
translateTo - пункт контекстного меню
selectTextRightClick - инструкция использования
targetLanguage - заголовок выбора языка
saveSettings - кнопка сохранения настроек
originalText - заголовок оригинального текста
translatedText - заголовок переведенного текста

Плейсхолдеры в переводах:

// Пример использования плейсхолдеров
"translateTo": {
  "message": "Translate to $1",
  "description": "Пункт контекстного меню"
}

// В коде:
const menuTitle = browser.i18n.getMessage("translateTo", [targetLangName]);
            

🔍 Тестирование локализации

Автоматическое определение

Установите userLang: "auto" для тестирования автоматического определения языка

Ручной выбор

Используйте выпадающий список в настройках для переключения между языками

Проверка всех элементов

Убедитесь, что переведены все элементы интерфейса и сообщения

Тестирование плейсхолдеров

Проверьте корректную замену $1, $2 и т.д. в переводах

⚠️ Частые проблемы

Отсутствующие ключи

Решение: Убедитесь, что все ключи из английской версии присутствуют в переводе

Неправильные плейсхолдеры

Решение: Проверьте соответствие количества $1, $2 в переводе и коде

Кодировка файлов

Решение: Сохраняйте JSON файлы в кодировке UTF-8

Синтаксические ошибки

Решение: Проверьте JSON на валидность с помощью JSON валидатора

← Назад: Технические детали Далее: Устранение неполадок →

🌍 Локализация BuxarTranslate