chrome.i18n

Descripción

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

Manifest

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 nueva configuración regional, 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):

En el directorio de la extensión: manifest.json, *.html, *.js, /_locates directory. En el directorio /_locates, se incluyen los directorios en, es y ko, cada uno con un archivo messages.json.

Compatibilidad con varios idiomas

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

Un archivo manifest.json y un archivo con JavaScript. El archivo .json tiene

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 de la extensión, los archivos CSS y el código de JavaScript usan el nombre de cada cadena para obtener su versión localizada.

A continuación, se muestra el aspecto de la extensión cuando está internacionalizada (ten en cuenta que todavía tiene solo cadenas en inglés):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="En el archivo manifest.json, " and="" was="" changed="" chrome.i18n.getmessage("extname").=""="" en="" file="" file="" new world="" hello="" in="" item="" hello="" in="" item/extensions/extensions.

Notas sobre la internacionalización:

  • Puedes usar cualquiera de las configuraciones regionales compatibles. Si usas una configuración regional no compatible, Google Chrome la ignorará.
  • En los archivos manifest.json y CSS, haz referencia a una cadena llamada messagename, como la siguiente:

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

    chrome.i18n.getMessage("messagename")
    
  • En cada llamada a getMessage(), puedes proporcionar hasta 9 strings para incluir 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 ver una lista completa de los nombres de los mensajes predefinidos.

  • En messages.json, cada cadena visible para el usuario tiene un nombre, un elemento de "mensaje" y un elemento de "descripción" opcional. 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 podrían no 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 configuración regional.

Una vez que una extensión se internacionaliza, traducirla es simple. Copias messages.json, lo traduces y colocas la copia en un directorio nuevo en /_locates. Por ejemplo, para admitir español, coloca una copia traducida de messages.json en /_locates/es. En la siguiente figura, se muestra la extensión anterior con una nueva traducción al español.

Se ve igual que la imagen anterior, pero con un nuevo archivo en /_locates/es/messages.json que contiene una traducción de los mensajes al español.

Mensajes predefinidos

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

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

En la siguiente tabla, se describe cada mensaje predefinido.

Nombre del mensajeDescripción
@@extension_idEs la extensión o el ID de la app. Puedes usar esta cadena para crear URLs para los 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_localeLa configuración regional actual. Puedes usar esta cadena para construir URL específicas de la configuración regional.
@@bidi_dirLa dirección del texto de la configuración regional actual. Puede ser "ltr" para los idiomas que se escriben de izquierda a derecha, como inglés, o "rtl", para los idiomas que se escriben de derecha a izquierda, como el árabe.
@@bidi_reversed_dirSi @@bidi_dir es "ltr", esto es "rtl"; de lo contrario, es "ltr".
@@bidi_start_edgeSi @@bidi_dir es "ltr", esto es "left"; de lo contrario, es "right".
@@bidi_end_edgeSi @@bidi_dir es "ltr", esto es "right"; de lo contrario, es "left".

El siguiente 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 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');

Este es un ejemplo del 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;
}

Para los idiomas que se leen de izquierda a derecha, como el inglés, las líneas en negrita se convierten en:

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

Configuración regional

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

Puedes localizar tu extensión para cualquier configuración regional que sea compatible con Chrome Web Store. Si tu configuración regional no aparece en esta lista, elige la alternativa más cercana. Por ejemplo, si la configuración regional predeterminada de la 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 Finlandés
fil Filipino
fr Francés
gu Guyaratí
he Hebreo
hi Hindi
h 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 Neerlandé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)

Cómo 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, se ejecutará tu extensión o app sin importar qué tan dispersa sea la traducción. El sistema de extensiones busca un mensaje de la siguiente manera:

  1. Busca en el archivo de mensajes (si corresponde) la configuración regional preferida del usuario. Por ejemplo, cuando la configuración regional de Google Chrome está establecida en inglés británico (en_GB), el sistema primero busca el mensaje en /_locates/en_GB/messages.json. Si ese archivo existe y el mensaje está allí, el sistema ya no buscará.
  2. Si la configuración regional preferida del usuario tiene una región (es decir, tiene un guion bajo: _), búscala 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 la configuración regional predeterminada en el archivo de mensajes. Por ejemplo, si la extensión “default_locale” de la extensión se establece en “es”, y ni /_locates/en_GB/messages.json ni /_locates/en/messages.json contienen el mensaje, la extensión usa el mensaje de /_locates/es/messages.json.

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

Cuatro archivos: manifest.json y tres messages.json (para es, en y en_GB)  Los archivos es y en muestran entradas para mensajes con

Establece la configuración regional de tu navegador

Para probar las traducciones, te recomendamos que establezcas la configuración regional de tu navegador. En esta sección, se explica cómo establecer la configuración regional en Windows, Mac OS X, Linux y ChromeOS.

Windows

Puedes cambiarla con una combinación de teclas específica de la configuración regional o en la IU de Google Chrome. El enfoque de combinación de teclas es más rápido, una vez que lo configuras, y te permite usar varios idiomas a la vez.

Usa una combinación de teclas específica para la configuración regional

Para crear y usar un acceso directo que inicie Google Chrome con una configuración regional en particular:

  1. Crea una copia del acceso directo de Google Chrome que ya está en el escritorio.
  2. Cambia el nombre del atajo 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 al 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 todas las combinaciones de teclas que desees, lo que facilita la prueba 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
Cómo usar la IU

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

  1. Ícono de la app > Opciones
  2. Elige la pestaña Avanzadas.
  3. Desplázate hacia abajo hasta Contenido web.
  4. Haz clic en Cambiar la configuración de fuente e idioma.
  5. Selecciona la pestaña Idiomas.
  6. Usa el menú desplegable para establecer el idioma de Google Chrome.
  7. Reinicia Chrome

Mac OS X

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

  1. En el menú de Apple, elige Preferencias del sistema
  2. En la sección Personal, elige Internacional.
  3. Elige tu idioma y ubicación
  4. Reinicia Chrome

Linux

Para cambiar la configuración regional en Linux, primero sal de Google Chrome. A continuación, todo en una línea, configura la variable de entorno LANGUAGE e inicia Google Chrome. Por ejemplo:

LANGUAGE=es ./chrome

ChromeOS

Para cambiar la configuración regional en ChromeOS, haz lo siguiente:

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

Ejemplos

Puedes encontrar ejemplos sencillos de internacionalización en el directorio examples/api/i18n. Para ver un ejemplo completo, consulta examples/extensions/news. Si deseas ver otros ejemplos y 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 con 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ías y usarías 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 lenguajes de aceptación del navegador y los muestra como una cadena separando cada lenguaje de aceptación con ','.

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 a partir de la cadena determinada 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

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. Para un idioma desconocido, se mostrará und, lo que significa que el CLD no reconoce el [percentage] del texto.

Tipo

cadena

Métodos

detectLanguage()

Promesa Chrome 47 y versiones posteriores
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Detecta el idioma del texto proporcionado mediante CLD.

Parámetros

  • text

    cadena

    Cadena de entrada del usuario para traducir.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera:

    (result: object) => void

    • resultado

      objeto

      Un objeto LanguageDetectionResult que conserva la confiabilidad del idioma detectado y el array de DetectedLanguage.

      • isReliable

        boolean

        El CLD detectó la confiabilidad del idioma

      • lenguajes

        objeto

        conjunto de detectedLanguage

        • language

          cadena

        • porcentaje

          número

          El porcentaje del idioma detectado

Devuelve

  • Promise<object>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAcceptLanguages()

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

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

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera:

    (languages: string[]) => void

    • lenguajes

      string[]

      Array de LanguageCode

Devuelve

  • Promise<LanguageCode[]>

    Chrome 99 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getMessage()

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

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

Parámetros

  • messageName

    cadena

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

  • substitutions

    Cualquier opcional

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

  • Opciones

    objeto opcional

    Chrome 79 y versiones posteriores
    • escapeLt

      booleano opcional

      Escape de < en la traducción a &lt;. Esto se aplica solo al mensaje en sí y no a los marcadores de posición. Se recomienda que los desarrolladores usen esta opción si la traducción se emplea en un contexto HTML. Las plantillas de cierre que se usan con Closure Compiler lo generan automáticamente.

Devuelve

  • cadena

    Mensaje localizado para la configuración regional actual.

getUILanguage()

chrome.i18n.getUILanguage()

Obtiene el idioma de la IU del navegador del navegador. Es diferente de i18n.getAcceptLanguages, que muestra los idiomas preferidos del usuario.

Devuelve

  • cadena

    El código de idioma de la IU del navegador, como en-US o fr-FR