Questa pagina è stata tradotta dall'API Cloud Translation.

chrome.i18n

Descrizione

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

Manifest

Se un'estensione ha una directory /_locales, il file 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 inglese (en), spagnolo (es) e 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.

Supporta più lingue

Supponiamo di avere 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 il titolo = "Hello World".

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 ottenere la relativa versione localizzata.

Ecco come appare l'estensione quando è internazionalizzata (tieni presente che ha 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 chrome.i18n.getMessage('extName'). Un nuovo file denominato /_locales/it/messages.json definisce "extName".

Alcune note sull'internazionalizzazione:

Puoi utilizzare una qualsiasi delle lingue supportate. Se utilizzi una lingua non supportata, Google Chrome la ignora.
Nei file manifest.json e CSS, fai riferimento a una stringa denominata messagename come segue:
```
__MSG_messagename__
```
Nel codice JavaScript dell'estensione o dell'app, fai riferimento a una stringa denominata messagename come segue:
```
chrome.i18n.getMessage("messagename")
```
In ogni chiamata a getMessage(), puoi fornire fino a 9 stringhe da includere nel messaggio. Per informazioni dettagliate, 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 facoltativo "description". Il nome è una chiave come "extName" o "search_string" che identifica la stringa. "message" specifica il valore della stringa in questa lingua. L'attributo facoltativo "description" 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 ulteriori informazioni, consulta Formati: messaggi specifici per le impostazioni internazionali.

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

È simile alla figura precedente, ma con un nuovo file in /_locales/it/messages.json che contiene una traduzione in italiano dei messaggi.

Messaggi predefiniti

Il sistema di internazionalizzazione fornisce alcuni messaggi predefiniti per aiutarti a eseguire la localizzazione. Questi includono @@ui_locale, che ti consente di rilevare la lingua dell'interfaccia utente corrente, e alcuni messaggi @@bidi_... che ti consentono di rilevare l'orientamento del testo. Questi ultimi messaggi hanno nomi simili alle costanti nell'API BIDI (bidirezionale) per i gadget.

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

La tabella seguente descrive ciascun messaggio predefinito.

Nome del messaggio	Descrizione
`@@extension_id`	L'ID estensione o app. Potresti 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. Potresti 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 da sinistra a destra come l'inglese o "rtl" per le lingue da destra a sinistra come l'arabo.
`@@bidi_reversed_dir`	Se `@@bidi_dir` è "ltr", il valore è "rtl"; altrimenti, è "ltr".
`@@bidi_start_edge`	Se `@@bidi_dir` è "ltr", significa "sinistra"; in caso contrario, è "destra".
`@@bidi_end_edge`	Se `@@bidi_dir` è "ltr", il valore è "right"; altrimenti, è "left".

Di seguito è riportato 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 di 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 scrittura da sinistra a destra, come l'inglese, le linee in grassetto diventano:

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

Impostazioni internazionali

Puoi scegliere tra molti codici paese, inclusi alcuni (ad esempio en) che consentono a una singola traduzione di supportare più varianti di una lingua (ad esempio en_GB e en_US).

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

Codice delle impostazioni internazionali	Lingua (regione)
ar	Arabo
am	Amarico
bg	Bulgaro
bn	Bengali
ca	Catalano
cs	Ceco
da	Danese
de	Tedesco
el	Greco
it	Inglese
en_AU	Inglese (Australia)
en_GB	Inglese (Gran Bretagna)
it_IT	Inglese (Stati Uniti)
es	Spagnolo
es_419	Spagnolo (America Latina e Caraibi)
et	Estone
fa	Persiano
fi	Finlandese
fil	Filippino
fr	Francese
gu	Gujarati
lui	Ebraico
hi	Hindi
h	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. Finché il file messages.json della lingua predefinita ha un valore per ogni stringa, l'estensione o l'app verrà eseguita indipendentemente da quanto sia scarsa una traduzione. Ecco come il sistema di estensioni cerca un messaggio:

Cerca nel file dei messaggi (se presente) la lingua preferita 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 fa altre ricerche.
Se le impostazioni internazionali preferite dall'utente hanno una regione (ovvero contengono un'underscore: _), cerca le impostazioni internazionali senza la 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 cerca altro.
Cerca le impostazioni internazionali predefinite nel file dei messaggi. Ad esempio, se "default_locale" dell'estensione è impostato 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 lingue supportate dall'estensione, ma "extName" è presente solo in due delle lingue. Dove un utente che utilizza Google Chrome in inglese americano vede l'etichetta "Colori", un utente che utilizza l'inglese britannico vede "Colours". Gli utenti che parlano sia inglese americano sia inglese britannico vedono il nome dell'estensione "Hello World". Poiché la lingua predefinita è lo spagnolo, gli utenti che utilizzano Google Chrome in una lingua diversa dall'inglese visualizzano 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 e en mostrano voci per i messaggi denominati "extName" e "colores"; il file en_GB ha una sola voce (per "colores").

Impostare le impostazioni internazionali del browser

Per testare le traduzioni, ti consigliamo di impostare le impostazioni internazionali del browser. Questa sezione spiega come impostare il codice lingua in Windows, Mac OS, 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 con le scorciatoie è più rapido, una volta configurato, e ti consente di utilizzare più lingue contemporaneamente.

Utilizzare una scorciatoia specifica per le impostazioni internazionali

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

Crea una copia della scorciatoia di Google Chrome già presente sul desktop.
Rinomina la nuova scorciatoia in base al nuovo codice lingua.
Modifica le proprietà della scorciatoia in modo che il campo Destinazione specifichi i flag --lang e --user-data-dir. Il target dovrebbe avere il seguente aspetto:
```
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 il seguente target:

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

Puoi creare tutte le scorciatoie che vuoi, in modo da testare facilmente 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. Avere una directory di dati per ogni lingua consente di eseguire il browser in più lingue contemporaneamente. Uno svantaggio è che, poiché i dati delle lingue non sono condivisi, devi installare l'estensione più volte, una volta per lingua, il che può essere complicato se non parli la lingua. Per scoprire di più, consulta la sezione Creare e utilizzare i profili.

Utilizzare l'interfaccia utente

Ecco come cambiare le impostazioni internazionali utilizzando l'interfaccia utente su Google Chrome per Windows:

Icona dell'app > Opzioni
Scegli la scheda Dietro le quinte.
Scorri fino a Contenuti web.
Fai clic su Modifica le impostazioni di caratteri e lingua.
Seleziona la scheda Lingue.
Utilizza il menu a discesa per impostare la lingua di Google Chrome.
Riavviare 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à
Riavviare Chrome

Linux

Per modificare le impostazioni internazionali su Linux, devi prima uscire da Google Chrome. Poi, in una sola riga, imposta la variabile di ambiente LANGUAGE e avvia Google Chrome. Ad esempio:

LANGUAGE=es ./chrome

ChromeOS

Per cambiare le impostazioni internazionali su ChromeOS:

Dal riquadro delle app in primo piano, 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 sul menu con tre puntini Altre azioni accanto alla lingua e scegli Mostra ChromeOS in questa lingua.
Fai clic sul pulsante Riavvia 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 per la visualizzazione del codice sorgente, consulta Samples.

getMessage()

Il seguente codice riceve un messaggio localizzato dal browser e lo mostra come stringa. Sostituisce due segnaposto all'interno del messaggio con le stringhe "stringa1" e "stringa2".

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 impostazioni internazionali. Per informazioni dettagliate sull'getMessage()chiamata, consulta il riferimento all'API.

getAcceptLanguages()

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

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

Per informazioni dettagliate sull'utilizzo di getAcceptLanguages(), consulta il riferimento all'API.

detectLanguage()

Il seguente codice rileva fino a tre lingue dalla stringa specificata e mostra 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 ulteriori dettagli sull'utilizzo di detectLanguage(inputText), consulta il riferimento all'API.

Tipi

LanguageCode

Chrome 47 e versioni successive

Un codice lingua ISO come 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 [percentuale] del testo è sconosciuta a CLD

Tipo

stringa

Metodi

detectLanguage()

Promessa Chrome 47 e versioni successive

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

Rileva la lingua del testo fornito utilizzando CLD.

Parametri

testo

stringa

Stringa di input dell'utente da tradurre.
callback

function facoltativa

Il parametro callback ha il seguente aspetto:
```
(result: object) => void
```
- risultato
  
  oggetto
  
  Oggetto LanguageDetectionResult che contiene l'affidabilità della lingua rilevata e l'array di DetectedLanguage
  - isReliable
    
    booleano
    
    Affidabilità della lingua rilevata da CLD
  - lingue
    
    object[]
    
    array di detectedLanguage
    
    language
    
    stringa
    
    percentuale
    
    numero
    
    La percentuale della lingua rilevata

Resi

Promise<object>

Chrome 99 e versioni successive

Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getAcceptLanguages()

Promessa

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

Recupera le lingue accettate del browser. È diverso dalle impostazioni internazionali utilizzate dal browser. Per ottenere le impostazioni internazionali, utilizza i18n.getUILanguage.

Parametri

callback

function facoltativa

Il parametro callback ha il seguente aspetto:
```
(languages: string[]) => void
```
- lingue
  
  stringa[]
  
  Array di LanguageCode

Resi

Promise<LanguageCode[]>

Chrome 99 e versioni successive

Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getMessage()

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

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.
sostituzioni

qualsiasi facoltativo

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

Oggetto facoltativo

Chrome 79 e versioni successive
- escapeLt
  
  booleano facoltativo
  
  Scappa da < 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 di chiusura utilizzati con Closure Compiler generano questo valore automaticamente.

Resi

stringa

Messaggio localizzato per le impostazioni internazionali correnti.

getUILanguage()

chrome.i18n.getUILanguage()

Restituisce la lingua dell'interfaccia utente del browser. È diverso da i18n.getAcceptLanguages che restituisce le lingue preferite dall'utente.

Resi

stringa

Il codice lingua dell'interfaccia utente del browser, ad esempio en-US o fr-FR.