Chrome ora supporta lo spazio dei nomi browser.* standardizzato (disponibile a partire da Chrome 148). Stiamo aggiornando gradualmente la documentazione. Scopri di più nella nostra guida alla transizione.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

browser.i18n

Descrizione

Utilizza l'infrastruttura chrome.i18n per implementare l'internazionalizzazione nell'intera app o estensione.

Manifest

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

Concetti e utilizzo

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

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

Nella directory dell'estensione: manifest.json, *.html, *.js, directory /_locales. Nella directory /_locales: le directory en, es e ko, ciascuna con un file messages.json.

Supporto di più lingue

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

Un file manifest.json e un file con JavaScript. Il file .json contiene "Hello World". Il file JavaScript ha title = 'Hello World'.

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

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

Nel file manifest.json, "Hello World" è stato modificato in "__MSG_extName__" e un nuovo elemento "default_locale" ha il valore "en". Nel file JavaScript, "Hello World" è stato modificato in browser.i18n.getMessage('extName'). Un nuovo file denominato /_locales/en/messages.json definisce "extName".

Alcune note sull'internazionalizzazione:

Puoi utilizzare una qualsiasi delle impostazioni internazionali supportate. Se utilizzi una lingua non supportata, Google Chrome la ignora.
Nei file manifest.json e CSS, fai riferimento a una stringa denominata messagename in questo modo:
```
__MSG_messagename__
```
Nel codice JavaScript dell'estensione o dell'app, fai riferimento a una stringa denominata messagename come segue:
```
browser.i18n.getMessage("messagename")
```
In ogni chiamata a getMessage(), puoi fornire fino a 9 stringhe da includere nel messaggio. Per maggiori dettagli, consulta Esempi: getMessage.
Alcuni messaggi, come @@bidi_dir e @@ui_locale, sono forniti dal sistema di internazionalizzazione. Per un elenco completo dei nomi dei messaggi predefiniti, consulta la sezione Messaggi predefiniti.
In messages.json, ogni stringa visibile all'utente ha un nome, un elemento "message" e un elemento "description" facoltativo. Il nome è una chiave come "extName" o "search_string" che identifica la stringa. "message" specifica il valore della stringa in questa lingua. La "descrizione" facoltativa fornisce assistenza ai traduttori, che potrebbero non essere in grado di 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 saperne di più, consulta Formati: messaggi specifici per le impostazioni internazionali.

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

L'immagine è la stessa della figura precedente, ma con un nuovo file in /_locales/es/messages.json che contiene una traduzione in spagnolo dei messaggi.

Messaggi predefiniti

Il sistema di internazionalizzazione fornisce alcuni messaggi predefiniti per aiutarti nella localizzazione. Questi includono @@ui_locale, in modo da poter rilevare le impostazioni internazionali dell'interfaccia utente corrente, e alcuni messaggi @@bidi_... che consentono di rilevare la direzione del testo. Questi ultimi messaggi hanno nomi simili alle costanti nell'API BIDI (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. Questo messaggio non funziona nei file manifest.

La tabella seguente descrive ogni messaggio predefinito.

Nome del messaggio	Descrizione
`@@extension_id`	L'ID dell'estensione o dell'app. Puoi utilizzare questa stringa per creare URL per le risorse all'interno dell'estensione. Anche le estensioni non localizzate possono utilizzare questo messaggio. Nota: non puoi utilizzare questo messaggio in un file manifest.
`@@ui_locale`	Le impostazioni internazionali correnti; puoi utilizzare questa stringa per creare URL specifici per le impostazioni internazionali.
`@@bidi_dir`	La direzione del testo per le impostazioni internazionali correnti, "ltr" per le lingue con scrittura da sinistra a destra, come l'inglese, o "rtl" per le lingue con scrittura da destra a sinistra, come l'arabo.
`@@bidi_reversed_dir`	Se `@@bidi_dir` è "ltr", questo valore è "rtl"; in caso contrario, è "ltr".
`@@bidi_start_edge`	Se `@@bidi_dir` è "ltr", il valore è "left"; in caso contrario, è "right".
`@@bidi_end_edge`	Se `@@bidi_dir` è "ltr", questo è "right"; in caso contrario, è "left".

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 estensione è abcdefghijklmnopqrstuvwxyzabcdef, la riga in grassetto nello 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 con direzione da sinistra a destra, come l'italiano, le linee in grassetto diventano:

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

Impostazioni internazionali

Puoi scegliere tra molte impostazioni internazionali, tra cui 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 tue impostazioni internazionali non sono elencate qui, scegli l'alternativa più vicina. Ad esempio, se le impostazioni internazionali predefinite dell'estensione sono "de_CH", scegli "de" nel Chrome Web Store.

Codice delle impostazioni internazionali	Lingua (regione)
`ar`	Arabo
`am`	Amarico
`bg`	Bulgaro
`bn`	Bengalese
`ca`	Catalano
`cs`	Ceco
`da`	Danese
`de`	Tedesco
`el`	Greco
`en`	Inglese
`en_AU`	Inglese (Australia)
`en_GB`	Inglese (Gran Bretagna)
`en_US`	Inglese (USA)
`es`	Spagnolo
`es_419`	Spagnolo (America Latina e Caraibi)
`et`	Estone
`fa`	Persiano
`fi`	Finlandese
`fil`	Filippino
`fr`	Francese
`gu`	Gujarati
`he`	Ebraico
`hi`	Hindi
`hr`	Croato
`hu`	Ungherese
`id`	Indonesiano
`it`	Italiano
`ja`	Giapponese
`kn`	Kannada
`ko`	Coreano
`lt`	Lituano
`lv`	Lettone
`ml`	Malayalam
`mr`	Marathi
`ms`	Malese
`nl`	Olandese
`no`	Norvegese
`pl`	Polacco
`pt_BR`	Portoghese (Brasile)
`pt_PT`	Portoghese (Portogallo)
`ro`	Rumeno
`ru`	Russo
`sk`	Slovacco
`sl`	Sloveno
`sr`	Serbo
`sv`	Svedese
`sw`	Swahili
`ta`	Tamil
`te`	Telugu
`th`	Thailandese
`tr`	Turco
`uk`	Ucraino
`vi`	Vietnamita
`zh_CN`	Cinese (Cina)
`zh_TW`	Cinese (Taiwan)

Cercare messaggi

Non è necessario definire ogni stringa per ogni lingua supportata. Se il file messages.json della lingua predefinita contiene un valore per ogni stringa, l'estensione o l'app verrà eseguita indipendentemente dalla completezza della traduzione. Ecco come il sistema delle estensioni cerca un messaggio:

Cerca nel file dei messaggi (se presente) le impostazioni internazionali preferite dell'utente. Ad esempio, quando le impostazioni internazionali di Google Chrome sono impostate su inglese britannico (en_GB), il sistema cerca prima il messaggio in /_locales/en_GB/messages.json. Se il file esiste e il messaggio è presente, il sistema non esegue ulteriori ricerche.
Se le impostazioni internazionali preferite dell'utente hanno una regione (ovvero, le impostazioni internazionali hanno un trattino basso: _), cerca le impostazioni internazionali senza quella regione. Ad esempio, se il file dei messaggi en_GB non esiste o non contiene il messaggio, il sistema cerca nel file dei messaggi en. Se il file esiste e il messaggio è presente, il sistema non esegue ulteriori ricerche.
Cerca il file dei messaggi per le impostazioni internazionali predefinite. Ad esempio, se l'estensione "default_locale" è impostata su "es" e né /_locales/en_GB/messages.json né /_locales/en/messages.json contengono il messaggio, l'estensione utilizza il messaggio di /_locales/es/messages.json.

Nella figura seguente, il messaggio denominato "colores" è presente in tutte e tre le impostazioni internazionali supportate dall'estensione, ma "extName" è presente solo in due impostazioni internazionali. Ovunque un utente che utilizza Google Chrome in inglese americano vede l'etichetta "Colors", un utente che utilizza l'inglese britannico vede "Colours". Sia gli utenti che parlano inglese americano sia quelli che parlano inglese britannico vedono il nome dell'estensione "Hello World". Poiché la lingua predefinita è lo spagnolo, gli utenti che eseguono Google Chrome in qualsiasi lingua diversa dall'inglese vedono l'etichetta "Colores" e il nome dell'estensione "Hola mundo".

Quattro file: manifest.json e tre file messages.json (per es, en ed en_GB). I file es ed en mostrano le voci per i messaggi denominati "extName" e "colores"; il file en_GB ha una sola voce (per "colores").

Imposta le impostazioni internazionali del browser

Per testare le traduzioni, potresti voler impostare le impostazioni internazionali del browser. Questa sezione spiega come impostare le impostazioni internazionali in Windows, macOS, Linux e ChromeOS.

Windows

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

Utilizza una scorciatoia specifica per le impostazioni internazionali

Per creare e utilizzare una scorciatoia che avvia Google Chrome con un'impostazione internazionale specifica:

Crea una copia della scorciatoia di Google Chrome già presente sul desktop.
Rinomina la nuova scorciatoia in modo che corrisponda alle nuove impostazioni internazionali.
Modifica le proprietà della scorciatoia in modo che il campo Destinazione specifichi i flag --lang e --user-data-dir. La destinazione dovrebbe avere un aspetto simile al seguente:
```
path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
```
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, semplificando i 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

Nota: la specifica di --user-data-dir è facoltativa, ma utile. La presenza di una directory di dati per ogni lingua ti consente di eseguire il browser in più lingue contemporaneamente. Uno svantaggio è che, poiché i dati delle impostazioni internazionali non vengono condivisi, devi installare l'estensione più volte, una per ogni impostazione internazionale, il che può essere difficile se non parli la lingua. Per saperne di più, consulta Creazione e utilizzo dei profili.

Utilizza la UI

Ecco come modificare le impostazioni internazionali utilizzando la UI su Google Chrome per Windows:

Icona dell'app > Opzioni
Scegli la scheda Under the Hood (Dietro le quinte)
Scorri fino a Contenuti web.
Fai clic su Modifica le impostazioni relative ai caratteri e alla lingua.
Scegli la scheda Lingue.
Utilizza il menu a discesa per impostare la lingua di Google Chrome.
Riavvia Chrome

Sistema operativo Mac

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

Dal menu Apple, scegli Preferenze di sistema.
Nella sezione Personale, scegli Internazionale.
Scegli la lingua e la località
Riavvia Chrome

Linux

Per modificare le impostazioni internazionali su Linux, esci prima da Google Chrome. Quindi, tutto su una riga, imposta la variabile di ambiente LANGUAGE e avvia Google Chrome. Ad esempio:

LANGUAGE=es ./chrome

ChromeOS

Per modificare le impostazioni internazionali su ChromeOS:

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

Esempi

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

getMessage()

Il seguente codice riceve un messaggio localizzato dal browser e lo visualizza come stringa. Sostituisce 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 saperne di più sui segnaposto, consulta la pagina Messaggi specifici per le impostazioni internazionali. Per maggiori dettagli sulla chiamata di getMessage(), consulta il Riferimento API.

getAcceptLanguages()

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

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

Per informazioni dettagliate sulla chiamata di getAcceptLanguages(), consulta il Riferimento API.

detectLanguage()

Il seguente codice rileva fino a 3 lingue dalla stringa specificata e visualizza il risultato come 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 di detectLanguage(inputText), consulta il Riferimento API.

Tipi

LanguageCode

Chrome 47+ browser.* da Chrome 148

Un codice lingua ISO, ad esempio en o fr. Per un elenco completo delle lingue supportate da questo metodo, consulta kLanguageInfoTable. Per una lingua sconosciuta, verrà restituito und, il che significa che [percentage] del testo è sconosciuto a CLD

Tipo

stringa

Metodi

detectLanguage()

Chrome 47+ browser.* da Chrome 148

browser.i18n.detectLanguage(
  text: string,
): Promise<object>

Rileva la lingua del testo fornito utilizzando CLD.

Parametri

testo

stringa

Stringa di input dell'utente da tradurre.

Resi

Promise<object>

Browser Chrome 99 e versioni successive .* da Chrome 148

getAcceptLanguages()

browser.i18n.getAcceptLanguages(): Promise<LanguageCode[]>

Recupera le lingue accettate dal browser. Questa impostazione è diversa da quella utilizzata dal browser. Per ottenere l'impostazione internazionale, utilizza i18n.getUILanguage.

Resi

Promise<LanguageCode[]>

Browser Chrome 99 e versioni successive .* da Chrome 148

getMessage()

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

Recupera la stringa localizzata per il messaggio specificato. Se il messaggio non è presente, questo metodo restituisce una stringa vuota (''). Se il formato della chiamata getMessage() è errato, ad esempio messageName non è una stringa o l'array substitutions contiene più di 9 elementi, questo metodo restituisce undefined.

Parametri

messageName

stringa

Il nome del messaggio, come specificato nel file messages.json.
substitutions

any optional

Fino a 9 stringhe di sostituzione, se il messaggio ne richiede.
opzioni

object facoltativo

Chrome 79 e versioni successive browser.* da Chrome 148
- escapeLt
  
  boolean facoltativo
  
  Escape < nella traduzione in <. Questo vale solo per il messaggio stesso, non per i segnaposto. Gli sviluppatori potrebbero voler utilizzare questa opzione se la traduzione viene utilizzata in un contesto HTML. I modelli Closure utilizzati con Closure Compiler lo generano automaticamente.

Resi

stringa

Messaggio localizzato per le impostazioni internazionali correnti.

getUILanguage()

browser.i18n.getUILanguage(): string

Recupera la lingua della UI del browser. Questo è diverso da i18n.getAcceptLanguages, che restituisce le lingue preferite dell'utente.

Resi

stringa

Il codice lingua della UI del browser, ad esempio en-US o fr-FR.

browser.i18n Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Descrizione

Manifest

Concetti e utilizzo

Supporto di più lingue

Messaggi predefiniti

Impostazioni internazionali

Cercare messaggi

Imposta le impostazioni internazionali del browser

Windows

Utilizza una scorciatoia specifica per le impostazioni internazionali

Utilizza la UI

Sistema operativo Mac

Linux

ChromeOS

Esempi

getMessage()

getAcceptLanguages()

detectLanguage()

Tipi

LanguageCode

Tipo

Metodi

detectLanguage()

Parametri

Resi

getAcceptLanguages()

Resi

getMessage()

Parametri

Resi

getUILanguage()

Resi

browser.i18n