Descrizione
Utilizza l'infrastruttura chrome.i18n
per implementare l'internazionalizzazione nell'intera app o estensione.
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
):
Come supportare 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="" _locales="" a="" alt="Nel file manifest.json, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" definisce="" en="" file="" / per" il file denominato="" in:
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 o un'app, la traduzione è semplice. Copia il file messages.json
,
lo traduci 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.
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.
Nome del messaggio | Descrizione |
---|---|
@@extension_id | L'estensione o l'ID app; puoi utilizzare questa stringa per creare gli URL per le risorse all'interno dell'estensione. Questo messaggio può essere utilizzato anche per le 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 il giapponese. |
@@bidi_reversed_dir | Se @@bidi_dir è "ltr", allora è "rtl"; altrimenti è "ltr". |
@@bidi_start_edge | Se @@bidi_dir è "ltr", è "sinistra"; in caso contrario, è "destra". |
@@bidi_end_edge | Se @@bidi_dir è "ltr", è "destra"; altrimenti è "sinistra". |
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
).
Impostazioni internazionali supportate
Puoi utilizzare qualsiasi lingua supportata nel Chrome Web Store.
Ricerca di 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:
- 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_locales/en_GB/messages.json
. Se il file esiste e il messaggio è presente, il sistema non effettua alcuna ricerca. - 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 messaggien
. Se il file esiste e il messaggio è presente, il sistema non effettua alcuna ricerca. - Cercare nel file dei messaggi le impostazioni internazionali predefinite. Ad esempio, se il valore "default_locale" dell'estensione è impostato su "es" e né
_locales/en_GB/messages.json
né_locales/en/messages.json
contiene il messaggio, l'estensione utilizza il messaggio proveniente da_locales/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".
Come 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.
Utilizzo di una scorciatoia specifica per le impostazioni internazionali
Per creare e utilizzare una scorciatoia che avvii Google Chrome con una lingua specifica:
- Crea una copia della scorciatoia di Google Chrome già presente sul desktop.
- Rinomina la nuova scorciatoia in modo che corrisponda alla nuova lingua.
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 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
Utilizzo dell'interfaccia utente
Ecco come modificare le impostazioni internazionali utilizzando l'interfaccia utente di Google Chrome per Windows:
- Icona dell'app > Opzioni
- Scegli la scheda Roba da smanettoni.
- Scorri verso il basso fino a Contenuti web.
- Fai clic su Cambia carattere e lingua
- Seleziona 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 Personali, scegli Internazionale
- Scegli la lingua e la località
- 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:
- Nella 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.
- 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.
- 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.
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.
Esempio: getAccettaLingue
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.
Esempio: 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.
Tipi
LanguageCode
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 il valore [percentage] del testo non è noto a CLD
Tipo
stringa
Metodi
detectLanguage()
chrome.i18n.detectLanguage(
text: string,
callback?: function,
)
Rileva la lingua del testo fornito utilizzando la metrica CLD.
Parametri
-
testo
stringa
Stringa inserita dall'utente da tradurre.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: object) => void
-
risultato
oggetto
Oggetto LanguageDetectionResult che contiene l'affidabilità della lingua e l'array DetectedLanguage rilevati
-
isReliable
boolean
CLD ha rilevato l'affidabilità del linguaggio
-
lingue
oggetto[]
array di DetectLanguage
-
language
stringa
-
percentuale
numero
La percentuale della lingua rilevata
-
-
-
Ritorni
-
Promise<object>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Recupera le lingue accettate del browser. È diversa dalle impostazioni internazionali utilizzate dal browser. Per recuperarle, utilizza i18n.getUILanguage
.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(languages: string[]) => void
-
lingue
stringa[]
Array di LanguageCode
-
Ritorni
-
Promise<LanguageCode[]>
Chrome 99 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getMessage()
chrome.i18n.getMessage(
messageName: string,
substitutions?: any,
options?: object,
)
Restituisce 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 sostitutions ha più di nove elementi, questo metodo restituisce undefined
.
Parametri
-
messageName
stringa
Il nome del messaggio, come specificato nel file
messages.json
. -
sostituzioni
qualsiasi facoltativo
Fino a nove stringhe di sostituzione, se il messaggio ne richiede una.
-
opzioni
oggetto facoltativo
Chrome 79 e versioni successive-
escapeLt
booleano facoltativo
Esegui l'escape di
<
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 il compilatore di Closure lo generano automaticamente.
-
Ritorni
-
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 degli utenti.
Ritorni
-
stringa
Il codice lingua dell'interfaccia utente del browser, ad esempio en-US o fr-FR.