Localizzazione - Documentazione BuxarTranslate

File: localization.html
Scopo: Guida alla localizzazione e aggiunta di nuove lingue

🌐 Lingue dell'interfaccia supportate

🇺🇸 English en

Lingua predefinita, supporto completo

🇷🇺 Russo ru

Localizzazione completa dell'interfaccia

🇩🇪 Deutsch de

Lingua dell'interfaccia tedesca

🇪🇸 Español es

Lingua dell'interfaccia spagnola

🇫🇷 Français fr

Lingua dell'interfaccia francese

🇮🇹 Italiano it

Lingua dell'interfaccia italiana

📁 Struttura della localizzazione

La localizzazione è organizzata secondo lo standard WebExtensions nella cartella _locales:

_locales/
├── en/
│   └── messages.json    # Traduzioni inglesi
├── ru/
│   └── messages.json    # Traduzioni russe  
├── de/
│   └── messages.json    # Traduzioni tedesche
├── es/
│   └── messages.json    # Traduzioni spagnole
├── it/
│   └── messages.json    # Traduzioni italiane
└── fr/
    └── messages.json    # Traduzioni francesi
            

📝 Formato dei file di traduzione

Ogni file messages.json contiene un oggetto con chiavi di traduzione:

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Nome dell'estensione"
  },
  "extensionDescription": {
    "message": "Translate selected text in emails with one click",
    "description": "Descrizione dell'estensione"
  },
  "translateTo": {
    "message": "Translate to $1",
    "description": "Voce del menu contestuale"
  },
  "selectTextRightClick": {
    "message": "Select text → Right-click → Translate",
    "description": "Istruzione nel popup"
  }
}
            

🔧 Aggiunta di una nuova lingua

1. Crea una cartella per la lingua

Crea una cartella con il codice lingua nella directory _locales/

mkdir _locales/ja # per la lingua giapponese

2. Crea il file messages.json

Crea il file di traduzione nella nuova cartella

touch _locales/ja/messages.json

3. Aggiungi le traduzioni

Copia la struttura dal file inglese e traduci tutti i valori

{
  "extensionName": {
    "message": "BuxarTranslate",
    "description": "Nome dell'estensione"
  },
  "translateTo": {
    "message": "Traduci in $1",
    "description": "Voce del menu contestuale"
  }
}
                

4. Aggiorna la scansione delle lingue

Aggiungi il codice lingua alla funzione scanAvailableLanguages() in popup.js

// Nel file popup.js
const possibleLangs = ['en', 'ru', 'es', 'de', 'fr', 'it', 'ja', 'zh', 'ko'];
// Aggiungi la tua lingua all'array possibleLangs
                

5. Testa la traduzione

Installa l'estensione e verifica il funzionamento della nuova lingua

🔄 Caricamento dinamico delle traduzioni

Il sistema carica dinamicamente le traduzioni per la lingua selezionata:

// Caricamento delle traduzioni per una lingua specifica
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;
}

// Gestore della lingua
const LanguageManager = {
  async init() {
    const storage = await browser.storage.local.get('userLang');
    const userLang = storage.userLang || 'auto';
    
    // Determina la lingua dell'interfaccia
    if (userLang === 'auto') {
      const uiLang = browser.i18n.getUILanguage();
      this.currentLang = uiLang.split('-')[0];
    } else {
      this.currentLang = userLang;
    }
    
    // Carica le traduzioni
    this.translations = await loadTranslations(this.currentLang) || {};
  }
};
            

🎯 Elementi chiave della traduzione

Chiavi obbligatorie da tradurre:

extensionName - nome dell'estensione
extensionDescription - descrizione dell'estensione
translateTo - voce del menu contestuale
selectTextRightClick - istruzioni per l'uso
targetLanguage - titolo della selezione della lingua
saveSettings - pulsante salva impostazioni
originalText - titolo del testo originale
translatedText - titolo del testo tradotto

Segnaposto nelle traduzioni:

// Esempio di utilizzo dei segnaposto
"translateTo": {
  "message": "Translate to $1",
  "description": "Voce del menu contestuale"
}

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

🔍 Test della localizzazione

Rilevamento automatico

Imposta userLang: "auto" per testare il rilevamento automatico della lingua

Selezione manuale

Utilizza il menu a tendina nelle impostazioni per passare da una lingua all'altra

Verifica di tutti gli elementi

Assicurati che tutti gli elementi dell'interfaccia e i messaggi siano tradotti

Test dei segnaposto

Verifica la corretta sostituzione di $1, $2, ecc. nelle traduzioni

⚠️ Problemi comuni

Chiavi mancanti

Soluzione: Assicurati che tutte le chiavi della versione inglese siano presenti nella traduzione

Segnaposto errati

Soluzione: Verifica la corrispondenza del numero di $1, $2 nella traduzione e nel codice

Codifica dei file

Soluzione: Salva i file JSON con codifica UTF-8

Errori di sintassi

Soluzione: Verifica la validità del JSON utilizzando un validatore JSON

← Indietro: Dettagli tecnici Avanti: Risoluzione dei problemi →

🌍 Localizzazione BuxarTranslate