browser.i18n

Descripción

Usa la infraestructura de chrome.i18n para implementar la internacionalización en toda tu app o extensión.

Manifiesto

Si una extensión tiene un directorio /_locales, el manifiesto debe definir "default_locale".

Conceptos y uso

Debes colocar todas las cadenas visibles para el usuario en un archivo llamado messages.json. Cada vez que agregas una configuración regional nueva, agregas un archivo de mensajes en un directorio llamado /_locales/_localeCode_, en el que localeCode es un código como en para inglés.

Esta es la jerarquía de archivos de una extensión internacionalizada que admite inglés (en), español (es) y coreano (ko):

Admite varios idiomas

Supongamos que tienes una extensión con los archivos que se muestran en la siguiente figura:

Para internacionalizar esta extensión, asigna un nombre a cada cadena visible para el usuario y colócala en un archivo de mensajes. El manifiesto, los archivos CSS y el código JavaScript de la extensión usan el nombre de cada cadena para obtener su versión localizada.

Así se ve la extensión cuando se internacionaliza (ten en cuenta que todavía tiene solo cadenas en inglés):

Algunas notas sobre la internacionalización:

• Puedes usar cualquiera de las configuraciones regionales compatibles. Si usas una configuración regional no admitida, Google Chrome la ignorará.

• En los archivos manifest.json y CSS, haz referencia a una cadena llamada messagename de la siguiente manera:

  __MSG_messagename__
  

• En el código JavaScript de tu extensión o app, haz referencia a una cadena llamada messagename de la siguiente manera:

  browser.i18n.getMessage("messagename")
  

• En cada llamada a getMessage(), puedes proporcionar hasta 9 cadenas para que se incluyan en el mensaje. Consulta Ejemplos: getMessage para obtener más detalles.

• El sistema de internacionalización proporciona algunos mensajes, como @@bidi_dir y @@ui_locale. Consulta la sección Mensajes predefinidos para obtener una lista completa de los nombres de los mensajes predefinidos.

• En messages.json, cada cadena visible para el usuario tiene un nombre, un elemento "message" y un elemento opcional "description". El nombre es una clave, como "extName" o "search_string", que identifica la cadena. El "mensaje" especifica el valor de la cadena en esta configuración regional. La "descripción" opcional proporciona ayuda a los traductores, que tal vez no puedan ver cómo se usa la cadena en tu extensión. Por ejemplo:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

Para obtener más información, consulta Formatos: Mensajes específicos de la configuración regional.

Una vez que se internacionaliza una extensión, traducirla es sencillo. Copia messages.json, tradúcelo y coloca la copia en un directorio nuevo en /_locales. Por ejemplo, para admitir el idioma español, solo debes colocar una copia traducida de messages.json en /_locales/es. En la siguiente figura, se muestra la extensión anterior con una nueva traducción al español.

Mensajes predefinidos

El sistema de internacionalización proporciona algunos mensajes predefinidos para ayudarte con la localización. Entre ellos, se incluyen @@ui_locale, para que puedas detectar la configuración regional actual de la IU, y algunos mensajes de @@bidi_... que te permiten detectar la dirección del texto. Estos últimos mensajes tienen nombres similares a las constantes de la API de gadgets BIDI (bidireccional).

El mensaje especial @@extension_id se puede usar en los archivos CSS y JavaScript, independientemente de si la extensión o la app están localizadas. Este mensaje no funciona en los archivos de manifiesto.

En la siguiente tabla, se describe cada mensaje predefinido.

Nombre del mensaje	Descripción
@@extension_id	Es el ID de la extensión o app. Puedes usar esta cadena para construir URLs de recursos dentro de la extensión. Incluso las extensiones no localizadas pueden usar este mensaje. Nota: No puedes usar este mensaje en un archivo de manifiesto.
@@ui_locale	Es la configuración regional actual. Puedes usar esta cadena para crear URLs específicas de la configuración regional.
@@bidi_dir	La dirección del texto para la configuración regional actual, ya sea "ltr" para idiomas de izquierda a derecha, como el inglés, o "rtl" para idiomas de derecha a izquierda, como el árabe.
@@bidi_reversed_dir	Si el @@bidi_dir es "ltr", este es "rtl"; de lo contrario, es "ltr".
@@bidi_start_edge	Si el @@bidi_dir es "ltr", entonces es "left"; de lo contrario, es "right".
@@bidi_end_edge	Si @@bidi_dir es "ltr", entonces es "right"; de lo contrario, es "left".

Este es un ejemplo de cómo usar @@extension_id en un archivo CSS para construir una URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Si el ID de la extensión es abcdefghijklmnopqrstuvwxyzabcdef, la línea en negrita del fragmento de código anterior se convierte en lo siguiente:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

A continuación, se muestra un ejemplo de uso de mensajes @@bidi_* en un archivo 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;
}

En el caso de los idiomas que se escriben de izquierda a derecha, como el inglés, las líneas en negrita se convierten en lo siguiente:

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

Configuraciones regionales

Puedes elegir entre muchas configuraciones regionales, incluidas algunas (como en) que permiten que una sola traducción admita varias variaciones de un idioma (como en_GB y en_US).

Puedes localizar tu extensión a cualquier configuración regional que admita Chrome Web Store. Si tu configuración regional no aparece aquí, elige la alternativa más cercana. Por ejemplo, si la configuración regional predeterminada de tu extensión es "de_CH", elige "de" en Chrome Web Store.

Código de configuración regional	Idioma (región)
ar	Árabe
am	Amárico
bg	Búlgaro
bn	Bengalí
ca	Catalán
cs	Checo
da	Danés
de	Alemán
el	Griego
en	Inglés
en_AU	Inglés (Australia)
en_GB	Inglés (Gran Bretaña)
en_US	Inglés (EE.UU.)
es	Español
es_419	Español (América Latina y el Caribe)
et	Estonio
fa	Persa
fi	Finés
fil	Filipino
fr	Francés
gu	Gujarati
he	Hebreo
hi	Hindi
hr	Croata
hu	Húngaro
id	Indonesio
it	Italiano
ja	Japonés
kn	Canarés
ko	Coreano
lt	Lituano
lv	Letón
ml	Malabar
mr	Maratí
ms	Malayo
nl	Holandés
no	Noruego
pl	Polaco
pt_BR	Portugués (Brasil)
pt_PT	Portugués (Portugal)
ro	Rumano
ru	Ruso
sk	Eslovaco
sl	Esloveno
sr	Serbio
sv	Sueco
sw	Suajili
ta	Tamil
te	Telugu
th	Tailandés
tr	Turco
uk	Ucraniano
vi	Vietnamita
zh_CN	Chino (China)
zh_TW	Chino (Taiwán)

Buscar mensajes

No es necesario que definas cada cadena para cada configuración regional admitida. Siempre que el archivo messages.json de la configuración regional predeterminada tenga un valor para cada cadena, tu extensión o app se ejecutará sin importar qué tan escasa sea la traducción. A continuación, se muestra cómo el sistema de extensiones busca un mensaje:

1. Busca en el archivo de mensajes (si existe) la configuración regional preferida del usuario. Por ejemplo, cuando la configuración regional de Google Chrome se establece en inglés británico (en_GB), el sistema primero busca el mensaje en /_locales/en_GB/messages.json. Si ese archivo existe y el mensaje está allí, el sistema no busca más.
2. Si la configuración regional preferida del usuario tiene una región (es decir, la configuración regional tiene un guion bajo: _), busca la configuración regional sin esa región. Por ejemplo, si el archivo de mensajes en_GB no existe o no contiene el mensaje, el sistema busca en el archivo de mensajes en. Si ese archivo existe y el mensaje está allí, el sistema no busca más.
3. Busca en el archivo de mensajes la configuración regional predeterminada. Por ejemplo, si el parámetro "default_locale" de la extensión se establece en "es", y ni /_locales/en_GB/messages.json ni /_locales/en/messages.json contienen el mensaje, la extensión usará el mensaje de /_locales/es/messages.json.

En la siguiente figura, el mensaje llamado "colores" se encuentra en las tres configuraciones regionales que admite la extensión, pero "extName" solo se encuentra en dos de ellas. Cuando un usuario que ejecuta Google Chrome en inglés de EE.UU. ve la etiqueta "Colors", un usuario de inglés británico ve "Colours". Tanto los usuarios de inglés de EE.UU. como los de inglés británico ven el nombre de la extensión "Hello World". Como el idioma predeterminado es el español, los usuarios que ejecutan Google Chrome en cualquier idioma que no sea el inglés ven la etiqueta "Colores" y el nombre de la extensión "Hola mundo".

Establece la configuración regional de tu navegador

Para probar las traducciones, te recomendamos que configures la región de tu navegador. En esta sección, se explica cómo configurar la configuración regional en Windows, macOS, Linux y ChromeOS.

Windows

Puedes cambiar la configuración regional con un acceso directo específico de la configuración regional o la IU de Google Chrome. Una vez que lo configures, el enfoque de acceso directo será más rápido y te permitirá usar varios idiomas a la vez.

Usa un acceso directo específico de la configuración regional

Para crear y usar un acceso directo que inicie Google Chrome con una configuración regional específica, sigue estos pasos:

1. Crea una copia del acceso directo de Google Chrome que ya está en tu escritorio.
2. Cambia el nombre del acceso directo nuevo para que coincida con la configuración regional nueva.

3. Cambia las propiedades del acceso directo para que el campo Destino especifique las marcas --lang y --user-data-dir. El destino debería ser similar a lo siguiente:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. Haz doble clic en el acceso directo para iniciar Google Chrome.

Por ejemplo, para crear un acceso directo que inicie Google Chrome en español (es), puedes crear un acceso directo llamado chrome-es que tenga el siguiente destino:

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

Puedes crear tantos atajos como quieras, lo que facilita las pruebas en varios idiomas. Por ejemplo:

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: Especificar --user-data-dir es opcional, pero útil. Tener un directorio de datos por configuración regional te permite ejecutar el navegador en varios idiomas al mismo tiempo. Una desventaja es que, como no se comparten los datos de las configuraciones regionales, debes instalar la extensión varias veces, una por configuración regional, lo que puede ser difícil si no hablas el idioma. Para obtener más información, consulta Crea y usa perfiles.

Cómo usar la IU

A continuación, se explica cómo cambiar la configuración regional con la IU en Google Chrome para Windows:

1. Ícono de la app > Opciones
2. Elige la pestaña Under the Hood.
3. Desplázate hasta Contenido web.
4. Haz clic en Cambiar la configuración de idioma y fuente.
5. Elige la pestaña Idiomas.
6. Usa el menú desplegable para configurar el idioma de Google Chrome.
7. Reiniciar Chrome

macOS

Para cambiar la configuración regional en Mac, usa las preferencias del sistema.

1. En el menú de Apple, elige Preferencias del Sistema.
2. En la sección Personal, elige Internacional.
3. Cómo elegir tu idioma y ubicación
4. Reiniciar Chrome

Linux

Para cambiar la configuración regional en Linux, primero sal de Google Chrome. Luego, en una sola línea, establece la variable de entorno LANGUAGE y, luego, inicia Google Chrome. Por ejemplo:

LANGUAGE=es ./chrome

ChromeOS

Para cambiar la configuración regional en ChromeOS, sigue estos pasos:

1. En la bandeja del sistema, elige Configuración.
2. En la sección Idiomas y entradas, elige el menú desplegable Idioma.
3. Si tu idioma no aparece en la lista, haz clic en Agregar idiomas y agrégalo.
4. Una vez que lo agregues, haz clic en el elemento de menú de 3 puntos Más acciones junto al idioma y elige Mostrar ChromeOS en este idioma.
5. Haz clic en el botón Reiniciar que aparece junto al idioma establecido para reiniciar ChromeOS.

Ejemplos

Puedes encontrar ejemplos de internacionalización en el directorio examples/api/i18n. Para ver un ejemplo completo, consulta examples/extensions/news. Para ver otros ejemplos y obtener ayuda para ver el código fuente, consulta Muestras.

getMessage()

El siguiente código obtiene un mensaje localizado del navegador y lo muestra como una cadena. Reemplaza dos marcadores de posición dentro del mensaje por las cadenas "string1" y "string2".

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

A continuación, se muestra cómo proporcionar y usar una sola cadena:

  // 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."
    }
  }
}

Para obtener más información sobre los marcadores de posición, consulta la página Mensajes específicos de la configuración regional. Para obtener detalles sobre cómo llamar a getMessage(), consulta la referencia de la API.

getAcceptLanguages()

El siguiente código obtiene los idiomas aceptados del navegador y los muestra como una cadena, separando cada idioma con una coma (,).

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

Para obtener detalles sobre cómo llamar a getAcceptLanguages(), consulta la referencia de la API.

detectLanguage()

El siguiente código detecta hasta 3 idiomas de la cadena proporcionada y muestra el resultado como cadenas separadas por líneas nuevas.

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;
  });
}

Para obtener más detalles sobre cómo llamar a detectLanguage(inputText), consulta la referencia de la API.

Tipos

LanguageCode

Chrome 47 y versiones posteriores browser.* desde Chrome 148

Es un código de idioma ISO, como en o fr. Para obtener una lista completa de los idiomas compatibles con este método, consulta kLanguageInfoTable. En el caso de un idioma desconocido, se devolverá und, lo que significa que el CLD no conoce el [porcentaje] del texto.

Tipo

string

Métodos

detectLanguage()

Chrome 47 y versiones posteriores browser.* desde Chrome 148

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

Detecta el idioma del texto proporcionado con CLD.

Parámetros

• texto

  string

  Es la cadena de entrada del usuario que se traducirá.

Muestra

• Promise<object>

  Chrome 99 y versiones posteriores browser.* desde Chrome 148

getAcceptLanguages()

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

Obtiene los idiomas aceptados del navegador. Esto es diferente de la configuración regional que usa el navegador. Para obtener la configuración regional, usa i18n.getUILanguage.

Muestra

• Promise<LanguageCode[]>

  Chrome 99 y versiones posteriores browser.* desde Chrome 148

getMessage()

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

Obtiene la cadena localizada para el mensaje especificado. Si falta el mensaje, este método devuelve una cadena vacía (''). Si el formato de la llamada a getMessage() es incorrecto (por ejemplo, messageName no es una cadena o el array substitutions tiene más de 9 elementos), este método devuelve undefined.

Parámetros

• messageName

  string

  Es el nombre del mensaje, como se especifica en el archivo messages.json.

• substitutions

  any optional

  Hasta 9 cadenas de sustitución, si el mensaje requiere alguna.

• opciones

  objeto opcional

  Chrome 79 y versiones posteriores browser.* desde Chrome 148
  • escapeLt

    booleano opcional

    Se escapa < en la traducción a <. Esto se aplica solo al mensaje, no a los marcadores de posición. Es posible que los desarrolladores quieran usar esta opción si la traducción se usa en un contexto HTML. Las plantillas de Closure que se usan con Closure Compiler generan esto automáticamente.

Muestra

• string

  Mensaje localizado para la configuración regional actual.

getUILanguage()

browser.i18n.getUILanguage(): string

Obtiene el idioma de la IU del navegador. Esto es diferente de i18n.getAcceptLanguages, que devuelve los idiomas preferidos del usuario.

Muestra

• string

  Es el código de idioma de la IU del navegador, como es-419 o fr-FR.