chrome.i18n

Descrizione

Manifest

Se un'estensione ha una directory /_locales, il manifest deve definire "default_locale".

Concetti e utilizzo

Devi inserire tutte le relative stringhe visibili all'utente in un file denominato messages.json. Ogni volta che aggiungi nuove impostazioni internazionali, aggiungi un file di messaggi in una directory denominata /_locales/_localeCode_, dove localeCode è un codice come en per l'inglese.

Ecco la gerarchia di file per un'estensione internazionalizzata che supporta inglese (en), spagnolo (es) e coreano (ko):

Supporto di più lingue

Supponiamo che tu disponga di un'estensione con i file mostrati nella seguente figura:

Per internazionalizzare questa estensione, assegna un nome a ogni stringa visibile all'utente e inseriscila in un file di messaggi. Il file manifest, i file CSS e il codice JavaScript dell'estensione utilizzano il nome di ogni stringa per ottenerne la versione localizzata.

Ecco come appare l'estensione quando viene internazionalizzata (tieni presente che ha ancora solo stringhe in inglese):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="Nel file manifest.json, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" definisce="" en="" file="" file="" kubectl" ha

Alcune note sull'internazionalizzazione:

• Puoi utilizzare una qualsiasi delle impostazioni internazionali supportate. Se utilizzi impostazioni internazionali non supportate, Google Chrome la ignora.

• Nei file manifest.json e CSS, fai riferimento a una stringa denominata messagename come la seguente:

  __MSG_messagename__
  

• Nel codice JavaScript dell'estensione o dell'app, fai riferimento a una stringa denominata messagename come questa:

  chrome.i18n.getMessage("messagename")
  

• In ogni chiamata a getMessage(), puoi specificare fino a 9 stringhe da includere nel messaggio. Per i dettagli, consulta Esempi: getMessage.

• Alcuni messaggi, come @@bidi_dir e @@ui_locale, sono forniti dal sistema di internazionalizzazione. Consulta la sezione Messaggi predefiniti per un elenco completo dei nomi dei messaggi predefiniti.

• In messages.json, ogni stringa visibile all'utente ha un nome, un elemento "messaggio" e una voce "descrizione" facoltativo. Il nome è una chiave come "extName" o "search_string" che identifica la stringa. "message" specifica il valore della stringa in queste impostazioni internazionali. La descrizione facoltativa aiuta i traduttori, che potrebbero non riuscire a vedere come viene utilizzata la stringa nell'estensione. Ad esempio:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

Per ulteriori informazioni, consulta Formati: messaggi specifici per le impostazioni internazionali.

Una volta internazionalizzata un'estensione, la traduzione è semplice. Copia il file messages.json, lo traduci e inserisci la copia in una nuova directory in /_locates. Ad esempio, per supportare lo spagnolo, inserisci una copia tradotta di messages.json in /_locates/es. La figura seguente mostra l'estensione precedente con una nuova traduzione in spagnolo.

Messaggi predefiniti

Il sistema di internazionalizzazione fornisce alcuni messaggi predefiniti per aiutarti a localizzare. tra cui @@ui_locale, che ti consente di rilevare le impostazioni internazionali attuali dell'interfaccia utente e alcuni messaggi @@bidi_... che ti consentono di rilevare la direzione del testo. Questi ultimi messaggi hanno nomi simili alle costanti nell'API BIdirezionale dei gadget.

Il messaggio speciale @@extension_id può essere utilizzato nei file CSS e JavaScript, indipendentemente dal fatto che l'estensione o l'app siano localizzate o meno. Questo messaggio non funziona nei file manifest.

La tabella seguente descrive ciascun messaggio predefinito.

Ecco un esempio di utilizzo di @@extension_id in un file CSS per creare un URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Se l'ID dell'estensione è abcdefghijklmnopqrstuvwxyzabcdef, la riga in grassetto dello snippet di codice precedente diventa:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

Ecco un esempio di utilizzo dei messaggi @@bidi_* in un file CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

Per le lingue da sinistra a destra come l'inglese, le righe in grassetto diventano:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

Lingue

Puoi scegliere tra diverse lingue, incluse alcune (come en), che consentono a una singola traduzione di supportare più varianti di una lingua (come en_GB e en_US).

Puoi localizzare l'estensione in qualsiasi lingua supportata dal Chrome Web Store. Se le impostazioni internazionali non sono elencate qui, scegli l'alternativa più simile. Ad esempio, se le impostazioni internazionali predefinite della tua estensione sono "de_CH", scegli "de" nel Chrome Web Store.

Cercare messaggi

Non è necessario definire ogni stringa per ogni impostazione internazionale supportata. Se il file messages.json delle impostazioni internazionali predefinite ha un valore per ogni stringa, l'estensione o l'app verrà eseguita a prescindere dalla scarsa traduzione. Ecco come il sistema di estensioni cerca un messaggio:

1. Cerca nel file dei messaggi (se presente) le impostazioni internazionali preferite dall'utente. Ad esempio, se le impostazioni internazionali di Google Chrome sono impostate sull'inglese britannico (en_GB), il sistema cerca per la prima volta il messaggio in /_locates/en_GB/messages.json. Se il file esiste e il messaggio è presente, il sistema non effettua alcuna ricerca.
2. Se l'impostazione internazionale preferita dall'utente include un'area geografica (ovvero, l'impostazione internazionale ha un trattino basso: _), cerca l'impostazione internazionale senza quella regione. Ad esempio, se il file di messaggi en_GB non esiste o non lo contiene, il sistema cerca nel file di messaggi en. Se il file esiste e il messaggio è presente, il sistema non effettua alcuna ricerca.
3. Cercare nel file dei messaggi le impostazioni internazionali predefinite. Ad esempio, se il valore "default_locale" dell'estensione è impostato su "es" e né /_locates/en_GB/messages.json né /_locates/en/messages.json contiene il messaggio, l'estensione utilizza il messaggio proveniente da /_locates/es/messages.json.

Nella figura seguente, il messaggio "colores" si trova in tutte e tre le impostazioni internazionali supportate dall'estensione, mentre "extName" si trova solo in due. Ogni volta che un utente che utilizza Google Chrome in inglese americano vede l'etichetta "Colori", un utente di inglese britannico vede "Colori". Sia gli utenti di inglese americano che britannici vedono l'estensione "Hello World". Poiché la lingua predefinita è lo spagnolo, gli utenti che utilizzano Google Chrome in una lingua diversa dall'inglese vedranno l'etichetta "Colori" e il nome dell'estensione "Hola mundo".

Impostare le impostazioni internazionali del browser

Per testare le traduzioni, è consigliabile impostare le impostazioni internazionali del browser. Questa sezione spiega come impostare le impostazioni internazionali in Windows, Mac OS X, Linux e ChromeOS.

Windows

Puoi modificare le impostazioni internazionali utilizzando una scorciatoia specifica per le impostazioni internazionali o l'interfaccia utente di Google Chrome. L'approccio basato sulle scorciatoie è più rapido una volta configurato e ti consente di utilizzare più lingue contemporaneamente.

Usa una scorciatoia specifica per le impostazioni internazionali

Per creare e utilizzare una scorciatoia che avvii Google Chrome con una lingua specifica:

1. Crea una copia della scorciatoia di Google Chrome già presente sul desktop.
2. Rinomina la nuova scorciatoia in modo che corrisponda alla nuova lingua.

3. Modifica le proprietà della scorciatoia in modo che il campo Target specifichi i flag --lang e --user-data-dir. Il target dovrebbe avere un aspetto simile al seguente:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. Avvia Google Chrome facendo doppio clic sulla scorciatoia.

Ad esempio, per creare una scorciatoia che avvii Google Chrome in spagnolo (es), puoi creare una scorciatoia denominata chrome-es con la seguente destinazione:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Puoi creare tutte le scorciatoie che vuoi per eseguire facilmente test in più lingue. Ad esempio:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko

Utilizzare l'interfaccia utente

Ecco come modificare le impostazioni internazionali utilizzando l'interfaccia utente di Google Chrome per Windows:

1. Icona dell'app > Opzioni
2. Scegli la scheda Roba da smanettoni.
3. Scorri verso il basso fino a Contenuti web.
4. Fai clic su Cambia carattere e lingua
5. Seleziona la scheda Lingue.
6. Utilizza il menu a discesa per impostare la lingua di Google Chrome.
7. Riavvia Chrome

Mac OS X

Per modificare le impostazioni internazionali su Mac, utilizza le preferenze di sistema.

1. Dal menu Apple, scegli Preferenze di Sistema
2. Nella sezione Personali, scegli Internazionale
3. Scegli la lingua e la località
4. Riavvia Chrome

Linux

Per modificare le impostazioni internazionali su Linux, devi prima uscire da Google Chrome. Dopodiché imposta la variabile di ambiente LANGUAGE e avvia Google Chrome. Ad esempio:

LANGUAGE=es ./chrome

ChromeOS

Per modificare le impostazioni internazionali su ChromeOS:

1. Nella barra delle applicazioni, scegli Impostazioni.
2. Nella sezione Lingue e immissione, scegli il menu a discesa Lingua.
3. Se la tua lingua non è presente nell'elenco, fai clic su Aggiungi lingue e aggiungila.
4. Dopo averla aggiunta, fai clic sulla voce di menu Altre azioni con tre puntini accanto alla tua lingua e scegli Visualizza ChromeOS in questa lingua.
5. Fai clic sul pulsante Riavvia visualizzato accanto alla lingua impostata per riavviare ChromeOS.

Esempi

Puoi trovare semplici esempi di internazionalizzazione nella directory examples/api/i18n. Per un esempio completo, consulta examples/extensions/news. Per altri esempi e per assistenza per la visualizzazione del codice sorgente, consulta la pagina Esempi.

getMessage()

Il seguente codice riceve un messaggio localizzato dal browser e lo visualizza come stringa. Sostituisci due segnaposto all'interno del messaggio con le stringhe "string1" e "string2".

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

Ecco come fornire e utilizzare una singola stringa:

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

Per ulteriori informazioni sui segnaposto, consulta la pagina Messaggi specifici per le lingue. Per maggiori dettagli sulla chiamata di getMessage(), consulta il riferimento API.

getAcceptLanguages()

Il seguente codice riceve le lingue accettate dal browser e le visualizza come stringa separando ogni lingua accettate con il simbolo ",".

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Per maggiori dettagli sulla chiamata a getAcceptLanguages(), consulta il riferimento API.

detectLanguage()

Il seguente codice rileva fino a 3 lingue dalla stringa specificata e mostra i risultati sotto forma di stringhe separate da nuove righe.

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

Per maggiori dettagli sulla chiamata a detectLanguage(inputText), consulta il riferimento API.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

chrome.i18n.getUILanguage()