chrome.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 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 aggiungi nuove impostazioni internazionali, aggiungi un file di messaggi in una directory denominata /_locales/_localeCode_, in cui localeCode è un codice come en per l'inglese.

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

Nella directory dell'estensione: manifest.json, *.html, *.js, /_locates. Nella directory /_locates: 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 include

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

Ecco come appare l'estensione quando è internazionalizzata (tieni presente che ha solo Stringhe in inglese):

<img "__msg_extname__",="" "default_locale"="" "it".="" "extname"."="" "hello="" _locates=&quot;&quot; a=&quot;&quot; alt="Nel file manifest.json, " and=&quot;&quot; was="" changed=&quot;&quot; chrome.i18n.getmessage("extname").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; new="" src=&quot;/static/docs/extensions/mv2/reference/i18n/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; value="" world"="" /&gt;

Alcune note sull'internazionalizzazione:

  • Puoi usare una qualsiasi delle località supportate. Se utilizzi una lingua non supportata, Google Chrome lo 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. Consulta Esempi: getMessage per informazioni dettagliate.

  • Alcuni messaggi, come @@bidi_dir e @@ui_locale, sono forniti dall'internazionalizzazione di un sistema operativo completo. 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 "messaggio" e un elemento facoltativo &quot;description&quot; molto utile. Il nome è una chiave come "extName" o "stringa_ricerca" che identifica stringa. Il "messaggio" specifica il valore della stringa in queste impostazioni internazionali. Il campo facoltativo "description" aiuta i traduttori, che potrebbero non essere in grado di vedere come viene usata la stringa nella . 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, traducilo e metti la copia in una nuova directory sotto /_locates. Ad esempio, per supportare Spagnolo, aggiungi una copia tradotta di messages.json in /_locates/es. La figura che segue mostra l'estensione precedente con una nuova traduzione in spagnolo.

È uguale all&#39;immagine precedente, ma con un nuovo file in /_locates/es/messages.json che contiene una traduzione spagnola dei messaggi.

Messaggi predefiniti

Il sistema di internazionalizzazione fornisce alcuni messaggi predefiniti utili per la localizzazione. Questi includi @@ui_locale, in modo da poter rilevare le impostazioni internazionali dell'interfaccia utente correnti e alcuni messaggi @@bidi_... che ti consentono di rilevare la direzione del testo. Questi ultimi messaggi hanno nomi simili alle costanti nei API per i gadget BIDI (bidirezionale).

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

Nella tabella seguente sono descritti tutti i messaggi predefiniti.

Nome del messaggioDescrizione
@@extension_idL'estensione o l'ID app; potresti 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_localeLe impostazioni internazionali correnti; potresti usare questa stringa per creare URL specifici delle impostazioni internazionali.
@@bidi_dirLa direzione del testo per la lingua corrente, "ltr". per lingue da sinistra a destra come inglese o "rtl" per le lingue da destra a sinistra come l'arabo.
@@bidi_reversed_dirSe @@bidi_dir è "ltr", allora è "rtl"; altrimenti si tratta di "ltr".
@@bidi_start_edgeSe @@bidi_dir è "ltr", significa "left"; altrimenti è "giusta".
@@bidi_end_edgeSe @@bidi_dir è "ltr", allora è "right"; 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 estensione è abcdefghijklmnopqrstuvwxyzabcdef, la riga in grassetto nel codice precedente lo snippet 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;

Impostazioni internazionali

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)
it_IT Inglese (USA)
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 tutte le impostazioni internazionali supportate. Se le impostazioni internazionali predefinite messages.json file ha un valore per ogni stringa, la tua estensione o l'app verrà eseguita indipendentemente da come sparsa di una traslazione. Ecco in che modo il sistema dell'estensione cerca un messaggio:

  1. Cerca nel file dei messaggi (se presente) le impostazioni internazionali preferite dall'utente. Ad esempio, quando Google Le impostazioni internazionali di 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 cerca non oltre.
  2. Se le impostazioni internazionali preferite dall'utente hanno una regione (ovvero, 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 di messaggi en. Se il file esiste il messaggio è presente, il sistema non cerca oltre.
  3. Cerca le impostazioni internazionali predefinite nel file dei messaggi. Ad esempio, se l'estensione "default_locale" è impostato su "es" e né /_locates/en_GB/messages.json/_locates/en/messages.json contiene il messaggio, l'estensione utilizza il messaggio da /_locates/es/messages.json.

Nella figura seguente, il messaggio denominato "colores" sia in tutte e tre le impostazioni internazionali in cui l'estensione supporta, ma "extName" solo in due località. Ogni volta che un utente che esegue Google Chrome negli Stati Uniti L'inglese vede l'etichetta "Colors", un utente dell'inglese britannico vede "Colours". Sia l'inglese (Stati Uniti) che Gli utenti di inglese britannico vedranno il nome dell'estensione "Hello World". Poiché la lingua predefinita è lo spagnolo, per gli utenti che utilizzano Google Chrome in lingue diverse dall'inglese vedi l'etichetta "Colores" e l'estensione nome "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 dei messaggi denominati

Impostare le impostazioni internazionali del browser

Per verificare le traduzioni, ti consigliamo di impostare le impostazioni internazionali del browser. Questa sezione spiega come impostare le impostazioni internazionali di 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. La l'approccio rapido è 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:

  1. Crea una copia del collegamento a Google Chrome già presente sul desktop.
  2. Rinomina la nuova scorciatoia in base alle nuove impostazioni internazionali.
  3. Modifica le proprietà della scorciatoia in modo che il campo Target (Destinazione) specifichi i valori --lang e --user-data-dir flag. 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 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:

  1. Icona dell'app > Opzioni
  2. Seleziona la scheda Roba da smanettoni.
  3. Scorri verso il basso fino a Contenuti web.
  4. Fai clic su Cambia carattere e lingua.
  5. Scegli 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 Personale, 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. Poi, tutto su una riga, imposta la lingua LANGUAGE variabile di ambiente e avvia Google Chrome. Ad esempio:

LANGUAGE=es ./chrome

ChromeOS

Per modificare le impostazioni internazionali su ChromeOS:

  1. Seleziona Impostazioni dalla barra delle applicazioni.
  2. Nella sezione Lingue e immissione, seleziona il menu a discesa Lingua.
  3. Se la tua lingua non è elencata, fai clic su Aggiungi lingue e aggiungila.
  4. 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.
  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 un esempio completo, consulta examples/extensions/news. Per altri esempi e per assistenza nella visualizzazione per il codice sorgente, consulta gli esempi.

getMessage()

Il seguente codice riceve un messaggio localizzato dal browser e lo visualizza come stringa. it 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 su per chiamare getMessage(), consulta il riferimento API.

getAcceptLanguages()

Il seguente codice ottiene le lingue accettate dal browser e le visualizza come stringa tramite 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 tre lingue della 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 a detectLanguage(inputText), consulta i riferimenti API.

Tipi

LanguageCode

Chrome 47 e versioni successive .

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()

Promesso 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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto:

    (result: object) => void

    • risultato

      oggetto

      Oggetto LanguageDetectionResult che contiene l'affidabilità delle lingue rilevate e l'array di DetectedLanguage

      • isReliable

        booleano

        Affidabilità della lingua rilevata da CLD

      • lingue

        object[]

        array di detectLanguage

        • language

          stringa

        • percentuale

          numero

          La percentuale di lingua rilevata

Resi

  • Promise&lt;object&gt;

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getAcceptLanguages()

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

Ottiene le lingue accettate del browser. Questa impostazione è diversa dalle impostazioni internazionali utilizzate dal browser, per ottenere le impostazioni internazionali, usa i18n.getUILanguage.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto:

    (languages: string[]) => void

    • lingue

      stringa[]

      Array di LanguageCode

Resi

  • Promise&lt;LanguageCode[]&gt;

    Chrome 99 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve 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 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

    oggetto facoltativo

    Chrome 79 e versioni successive .
    • escapeLt

      booleano facoltativo

      Sequenza di escape < trascritta in &lt;. 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.

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 dell'utente.

Resi

  • stringa

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