Dettagli tecnici - Documentazione BuxarTranslate

File: technical.html
Scopo: Informazioni tecniche su architettura, API e struttura interna

📁 Struttura del progetto

buxartranslate/ ├── manifest.json # Configurazione dell'estensione ├── background.js # Script di background (logica principale) ├── popup.html # Interfaccia popup ├── popup.js # Logica popup ├── icons/ # Icone dell'estensione │ ├── icon-16.png │ ├── icon-32.png │ ├── icon-48.png │ ├── icon-64.png │ └── icon-128.png └── _locales/ # Localizzazione ├── en/ │ └── messages.json ├── ru/ │ └── messages.json ├── de/ │ └── messages.json ├── es/ │ └── messages.json ├── it/ │ └── messages.json └── fr/ └── messages.json

🔑 File chiave

manifest.json

Tipo: WebExtension per Thunderbird

Versione API: 78.0+

Permessi: storage, menus, notifications, activeTab

background.js

Scopo: Logica principale dell'estensione

Funzioni: Menu contestuale, API traduzioni, gestione finestre

popup.js

Scopo: Logica dell'interfaccia delle impostazioni

Funzioni: Gestione impostazioni, ricerca lingue, localizzazione

🌐 API e integrazioni

Google Translate API

Rilevamento lingua: https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=en&dt=ld&q=...

Traduzione testo: https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=it&dt=t&q=...

// Funzione di traduzione tramite API Google
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

Creazione e gestione del menu contestuale

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

browser.storage

Memorizzazione impostazioni e dati

// Salvataggio impostazioni
await browser.storage.local.set(settings);

// Caricamento impostazioni  
const settings = await browser.storage.local.get(defaultSettings);
                    

browser.notifications

Visualizzazione notifiche di sistema

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

browser.windows

Gestione finestre di traduzione

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

🔄 Sistema di messaggistica

Comunicazione tra i componenti dell'estensione:

// Gestore messaggi in 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") {
    // ... gestione richiesta impostazioni
  }
  
  if (request.action === "saveSettings") {
    // ... gestione salvataggio impostazioni
  }
});
            

💾 Memorizzazione dati

// Struttura dati in localStorage
{
  // Impostazioni utente
  "translateTo": "it",
  "autoDetectLanguage": true,
  "windowDisplayTime": 30,
  "userLang": "auto",
  
  // Lingue utilizzate di recente
  "recentLanguages": ["it", "en", "es", "fr", "de"],
  
  // Cronologia traduzioni
  "lastTranslation": {
    "original": "Hello world",
    "translated": "Ciao mondo",
    "sourceLang": "en", 
    "targetLang": "it",
    "timestamp": 1700000000000,
    "translator": "google"
  },
  
  // ID finestra di traduzione aperta
  "translationWindowId": 12345
}
            

🔧 Architettura dell'estensione

Struttura componenti

Background Script - logica principale, menu contestuale, chiamate API
Popup Interface - interfaccia utente per impostazioni
Translation Window - finestra separata per visualizzazione traduzioni
Localization System - supporto multilingue dell'interfaccia

Flusso dati

Utente seleziona testo → menu contestuale
Background script riceve testo → rileva lingua
Richiesta a Google Translate API → riceve traduzione
Salvataggio traduzione → mostra notifica e finestra
Aggiornamento interfaccia popup con cronologia traduzioni

🛡️ Sicurezza

Connessioni HTTPS

Tutte le richieste all'API Google vengono eseguite tramite protocollo HTTPS sicuro

Memorizzazione locale

Impostazioni e dati utente memorizzati localmente nel browser

Permessi minimi

L'estensione richiede solo i permessi necessari per il funzionamento

Gestione errori

Sistema complesso di gestione e visualizzazione errori all'utente

← Indietro: Impostazioni Avanti: Localizzazione →

🔧 Dettagli tecnici BuxarTranslate