Descrizione
Utilizza l'infrastruttura chrome.i18n
per implementare l'internazionalizzazione nell'intera app o 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 nuove impostazioni internazionali, devi aggiungere un file di messaggi in una directory denominata /_locales/_localeCode_
, dove localeCode è un codice come en
per l'inglese.
Di seguito è riportata la gerarchia dei file per un'estensione internazionalizzata che supporta inglese (en
), spagnolo (es
) e coreano (ko
):
Supporto di più lingue
Supponiamo che tu abbia un'estensione con i file mostrati nella figura seguente:
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 versione localizzata.
Ecco come appare l'estensione quando è internazionalizzata (tieni presente che ha 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="" messages" src.
Alcune note sull'internazionalizzazione:
- Puoi usare una qualsiasi delle località 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 questa:__MSG_messagename__
Nel codice JavaScript dell'estensione o dell'app, fai riferimento a una stringa denominata messagename come la seguente:
chrome.i18n.getMessage("messagename")
In ogni chiamata a
getMessage()
, puoi inserire 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 "messaggio" e un elemento "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. L'elemento facoltativo "description" fornisce assistenza ai traduttori, che potrebbero non essere in grado di vedere come viene utilizzata la stringa nella tua 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 la sezione Formati: messaggi specifici per le impostazioni internazionali.
Quando un'estensione viene internazionalizzata, tradurla è semplice. Copia messages.json
, traduci il testo e inseriscilo in una nuova directory in /_locates
. Ad esempio, per supportare lo spagnolo, basta mettere 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 utili per la localizzazione. Includono @@ui_locale
, che consente di rilevare le impostazioni internazionali della UI correnti 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 o meno. Questo messaggio non funziona nei file manifest.
Nella tabella seguente sono descritti tutti i messaggi predefiniti.
Nome del messaggio | Descrizione |
---|---|
@@extension_id | L'estensione o l'ID app. Puoi usare questa stringa per creare URL per le risorse all'interno dell'estensione. Questo messaggio può essere usato anche dalle estensioni non localizzate. Nota: non puoi utilizzare questo messaggio in un file manifest. |
@@ui_locale | Le impostazioni internazionali correnti; potresti usare questa stringa per creare URL specifici delle impostazioni internazionali. |
@@bidi_dir | La direzione del testo per la lingua corrente, "ltr" per le lingue 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", allora è "rtl", altrimenti è "ltr". |
@@bidi_start_edge | Se @@bidi_dir è "ltr", allora è "left"; in caso contrario, è "right". |
@@bidi_end_edge | Se @@bidi_dir è "ltr", allora è "right"; altrimenti, è "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 da sinistra a destra come l'inglese, le linee in grassetto diventano:
dir: ltr;
padding-left: 0;
padding-right: 1.5em;
Lingue
Puoi scegliere tra molte impostazioni internazionali, tra cui alcune (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 è inclusa nell'elenco, scegli quella più simile. Ad esempio, se le impostazioni internazionali predefinite dell'estensione sono "de_CH"
, scegli "de"
nel Chrome Web Store.
Codice 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) |
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 |
h | Croato |
hu | Ungherese |
ID | Indonesiano |
che li ricevano. | 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 tutte le impostazioni internazionali supportate. Se il file messages.json
delle impostazioni internazionali predefinite ha un valore per ogni stringa, l'estensione o l'app verrà eseguita indipendentemente dalla scarsa qualità della traduzione. Ecco come il sistema di estensione cerca un messaggio:
- 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 innanzitutto il messaggio in/_locates/en_GB/messages.json
. Se il file esiste e il messaggio è presente, il sistema non esegue alcuna ricerca. - Se le impostazioni internazionali preferite dall'utente hanno una regione (ovvero, hanno un trattino basso: _), cerca quelle senza quella regione. Ad esempio, se il file dei messaggi
en_GB
non esiste o non contiene il messaggio, il sistema cerca nel file di messaggien
. Se il file esiste e il messaggio è presente, il sistema non cerca oltre. - Cerca le impostazioni internazionali predefinite nel file dei messaggi. Ad esempio, se il valore "default_locale" dell'estensione è impostato su "es" e né
/_locates/en_GB/messages.json
né/_locates/en/messages.json
contengono il messaggio, l'estensione utilizza il messaggio proveniente da/_locates/es/messages.json
.
Nella figura seguente, il messaggio denominato "colores" è presente in tutte e tre le lingue supportate dall'estensione, mentre "extName" è presente soltanto in due. Ogni volta che un utente che esegue Google Chrome in inglese americano vede l'etichetta "Colors", un utente di inglese britannico vede "Colori". Sia l'inglese americano che l'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 vedranno l'etichetta "Colores" e il nome dell'estensione "Hola mundo".
Impostare le impostazioni internazionali del browser
Per verificare le traduzioni, ti consigliamo di impostare le impostazioni internazionali del browser. Questa sezione spiega come configurare 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'UI di Google Chrome. L'approccio con scorciatoia è più rapido, una volta configurato, e ti consente di utilizzare diverse lingue contemporaneamente.
Usa una scorciatoia specifica per le impostazioni internazionali
Per creare e utilizzare una scorciatoia che avvii Google Chrome con una lingua specifica:
- Crea una copia del collegamento a Google Chrome già presente sul desktop.
- Rinomina la nuova scorciatoia in base alle nuove impostazioni internazionali.
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
Avvia Google Chrome facendo doppio clic sulla scorciatoia.
Ad esempio, per creare una scorciatoia che avvia 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 per poter 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
Utilizzo dell'interfaccia utente
Per modificare le impostazioni internazionali utilizzando l'interfaccia utente di Google Chrome per Windows:
- Icona dell'app > Opzioni
- Seleziona la scheda Roba da smanettoni.
- Scorri verso il basso fino a Contenuti web.
- Fai clic su Cambia carattere e lingua.
- Scegli la scheda Lingue.
- Utilizza il menu a discesa per impostare la lingua di Google Chrome
- Riavvia Chrome
Mac OS X
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, devi prima uscire 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:
- Seleziona Impostazioni dalla barra delle applicazioni.
- Nella sezione Lingue e immissione, seleziona il menu a discesa Lingua.
- Se la tua lingua non è elencata, fai clic su Aggiungi lingue e aggiungila.
- Dopo l'aggiunta, fai clic sulla voce di menu con tre puntini Altre azioni accanto alla tua lingua e scegli Visualizza ChromeOS in questa lingua.
- 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 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 ulteriori informazioni sui segnaposto, consulta la pagina Messaggi specifici per lingua. Per maggiori dettagli sulla chiamata a getMessage()
, consulta i riferimenti per le API.
getAcceptLanguages()
Il seguente codice riceve le lingue accettate dal browser e le visualizza come stringa separando ogni lingua accettata con ",".
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 della stringa specificata e mostra il risultato 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 i riferimenti API.
Tipi
LanguageCode
Un codice lingua ISO, ad esempio en
o fr
. Per un elenco completo delle lingue supportate da questo metodo, vedi kLanguageInfoTable. Per una lingua sconosciuta, verrà restituito und
, il che significa che la percentuale [percentage] del testo è sconosciuta a CLD
Tipo
stringa
Metodi
detectLanguage()
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
funzione facoltativa
Il parametro
callback
ha un aspetto simile al seguente:(result: object) => void
-
risultato
oggetto
Oggetto LanguageDetectionResult che contiene l'affidabilità delle lingue rilevate e l'array di DetectedLanguage
-
isReliable
boolean
Affidabilità della lingua rilevata da CLD
-
lingue
oggetto[]
array di detectLanguage
-
language
stringa
-
percentuale
numero
La percentuale di lingua rilevata
-
-
-
Valori restituiti
-
Promise<object>
Chrome 99 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Ottiene le lingue accettate del browser. È diversa da quella utilizzata dal browser; per ottenere le impostazioni internazionali, usa i18n.getUILanguage
.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha un aspetto simile al seguente:(languages: string[]) => void
-
lingue
stringa[]
Array di LanguageCode
-
Valori restituiti
-
Promise<LanguageCode[]>
Chrome 99 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per la compatibilità con le versioni precedenti. Non puoi utilizzare 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()
non è corretto, ad esempio messageName non è una stringa o l'array substitutions contiene più di nove elementi, questo metodo restituisce undefined
.
Parametri
-
messageName
stringa
Il nome del messaggio, come specificato nel file
messages.json
. -
sostituzioni
qualsiasi opzione facoltativa
Fino a 9 stringhe di sostituzione, se il messaggio ne richiede una.
-
opzioni del modello.
oggetto facoltativo
Chrome 79 e versioni successive-
escapeLt
booleano facoltativo
Sequenza di escape
<
trascritta in<
. Questo vale solo per il messaggio stesso, non per i segnaposto. Gli sviluppatori possono utilizzarla se la traduzione viene utilizzata in un contesto HTML. I modelli di chiusura utilizzati con Closure Compiler generano automaticamente questo errore.
-
Valori restituiti
-
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 dell'utente.
Valori restituiti
-
stringa
Il codice della lingua dell'interfaccia utente del browser, ad esempio en-US o fr-FR.