Технические детали - BuxarTranslate Документация

Файл: technical.html
Назначение: Техническая информация об архитектуре, API и внутреннем устройстве

📁 Структура проекта

buxartranslate/ ├── manifest.json # Конфигурация расширения ├── background.js # Фоновый скрипт (основная логика) ├── popup.html # Интерфейс popup ├── popup.js # Логика popup ├── icons/ # Иконки расширения │ ├── icon-16.png │ ├── icon-32.png │ ├── icon-48.png │ ├── icon-64.png │ └── icon-128.png └── _locales/ # Локализация ├── en/ │ └── messages.json ├── ru/ │ └── messages.json ├── de/ │ └── messages.json ├── es/ │ └── messages.json ├── it/ │ └── messages.json └── fr/ └── messages.json

🔑 Ключевые файлы

manifest.json

Тип: WebExtension для Thunderbird

Версия API: 78.0+

Разрешения: storage, menus, notifications, activeTab

background.js

Назначение: Основная логика расширения

Функции: Контекстное меню, API переводов, управление окнами

popup.js

Назначение: Логика интерфейса настроек

Функции: Управление настройками, поиск языков, локализация

🌐 API и интеграции

Google Translate API

Определение языка: https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=en&dt=ld&q=...

Перевод текста: https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=ru&dt=t&q=...

// Функция перевода через Google API
async function translateWithGoogle(text, sourceLang, targetLang) {
  const url = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=${sourceLang}&tl=${targetLang}&dt=t&q=${encodeURIComponent(text)}`;
  const response = await fetch(url);
  
  if (!response.ok) {
    throw new Error(`Google API error: ${response.status}`);
  }
  
  const data = await response.json();
  let translatedText = "";
  
  if (data && data[0]) {
    data[0].forEach(item => {
      if (item[0]) translatedText += item[0];
    });
  }
  
  return preserveLineBreaks(translatedText || text, text);
}
            

Thunderbird WebExtension API

browser.menus

Создание и управление контекстным меню

browser.menus.create({
  id: "translate",
  title: menuTitle,
  contexts: ["selection"]
});
                    

browser.storage

Хранение настроек и данных

// Сохранение настроек
await browser.storage.local.set(settings);

// Загрузка настроек  
const settings = await browser.storage.local.get(defaultSettings);
                    

browser.notifications

Показ системных уведомлений

browser.notifications.create({
  type: "basic",
  iconUrl: "icon.png",
  title: title,
  message: message
});
                    

browser.windows

Управление окнами перевода

const translationWindow = await browser.windows.create({
  url: url,
  type: 'popup',
  width: 550,
  height: 600
});
                    

🔄 Система сообщений

Коммуникация между компонентами расширения:

// Обработчик сообщений в background.js
browser.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === "getTranslation") {
    browser.storage.local.get("lastTranslation").then(result => {
      sendResponse(result);
    });
    return true;
  }
  
  if (request.action === "getSettings") {
    // ... обработка запроса настроек
  }
  
  if (request.action === "saveSettings") {
    // ... обработка сохранения настроек
  }
});
            

💾 Хранение данных

// Структура данных в localStorage
{
  // Настройки пользователя
  "translateTo": "ru",
  "autoDetectLanguage": true,
  "windowDisplayTime": 30,
  "userLang": "auto",
  
  // Последние используемые языки
  "recentLanguages": ["ru", "en", "es", "fr", "de"],
  
  // История переводов
  "lastTranslation": {
    "original": "Hello world",
    "translated": "Привет мир",
    "sourceLang": "en", 
    "targetLang": "ru",
    "timestamp": 1700000000000,
    "translator": "google"
  },
  
  // ID открытого окна перевода
  "translationWindowId": 12345
}
            

🔧 Архитектура расширения

Компонентная структура

Background Script - основная логика, контекстное меню, API вызовы
Popup Interface - пользовательский интерфейс для настроек
Translation Window - отдельное окно для отображения переводов
Localization System - многоязычная поддержка интерфейса

Поток данных

Пользователь выделяет текст → контекстное меню
Background script получает текст → определяет язык
Запрос к Google Translate API → получение перевода
Сохранение перевода → показ уведомления и окна
Обновление интерфейса popup с историей переводов

🛡️ Безопасность

HTTPS соединения

Все запросы к Google API выполняются по защищенному HTTPS протоколу

Локальное хранение

Настройки и данные пользователя хранятся локально в браузере

Минимальные разрешения

Расширение запрашивает только необходимые для работы разрешения

Обработка ошибок

Комплексная система обработки и отображения ошибок пользователю

← Назад: Настройки Далее: Локализация →

🔧 Технические детали BuxarTranslate