chrome.i18n

Descripción

Debes colocar todas sus 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_, donde localeCode es un código como en para inglés.

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

Cómo admitir varios idiomas

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

Para internacionalizar esta extensión, debes nombrar cada cadena visible para el usuario y colocarla 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 solo tiene cadenas en inglés):

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="In the manifest.json file, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

Algunas notas sobre la internacionalización:

• Puedes usar cualquiera de las configuraciones regionales admitidas. 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 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:

  chrome.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.

• Algunos mensajes, como @@bidi_dir y @@ui_locale, los proporciona el sistema de internacionalización. 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 "description" 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 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 o una app, traducirla es sencillo. Copias messages.json, lo traduces y colocas la copia en un directorio nuevo en _locales. Por ejemplo, para admitir español, solo tienes que 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. Estos incluyen @@ui_locale, por lo que puedes 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 BIDI (bidireccional) de gadgets.

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.

A continuación, se muestra un ejemplo del uso de @@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:

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

A continuación, se incluye 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 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 variantes de un idioma (como en_GB y en_US).

Configuraciones regionales admitidas

Puedes usar cualquiera de las configuraciones regionales que admite Chrome Web Store.

Búsqueda de mensajes

No es necesario que definas cada cadena para cada configuración regional admitida. Siempre y cuando 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 una traducción. A continuación, se explica cómo el sistema de extensiones busca un mensaje:

1. Busca en el archivo de mensajes (si hay alguno) 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 la configuración regional predeterminada en el archivo de mensajes. Por ejemplo, si el parámetro "default_locale" de la extensión está establecido en "es" y ni _locales/en_GB/messages.json ni _locales/en/messages.json contienen el mensaje, la extensión usa 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. Dondequiera que un usuario que ejecute Google Chrome en inglés de EE.UU. vea la etiqueta "Colors", un usuario de inglés británico verá "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". Dado que el idioma predeterminado es el español, los usuarios que ejecutan Google Chrome en cualquier idioma que no sea inglés ven la etiqueta "Colores" y el nombre de la extensión "Hola mundo".

Cómo configurar la configuración regional de tu navegador

Para probar las traducciones, es posible que desees configurar la configuración regional de tu navegador. En esta sección, se explica cómo configurar la configuración regional en Windows, Mac OS X, Linux y ChromeOS.

Windows

Puedes cambiar la configuración regional con un atajo específico para la configuración regional o con la IU de Google Chrome. El método de acceso directo es más rápido una vez que lo configuras y te permite usar varios idiomas a la vez.

Cómo usar un atajo 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, haz lo siguiente:

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

3. Cambia las propiedades del acceso directo de modo que el campo Target especifique las marcas --lang y --user-data-dir. El destino debería verse así:

   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 accesos directos 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

Usa la IU

Sigue estos pasos para 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 hacia abajo 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. Reinicia Chrome

Mac OS X

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. Elige tu idioma y ubicación
4. Reinicia Chrome

Linux

Para cambiar la configuración regional en Linux, primero cierra Google Chrome. Luego, en una sola línea, configura 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 entrada, 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 a tu 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 simples 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 Ejemplos.

Ejemplos: 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 "cadena1" y "cadena2".

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.

Ejemplo: getAcceptLanguages

El siguiente código obtiene los idiomas aceptados del navegador y los muestra como una cadena separada por ",".

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.

Ejemplo: detectLanguage

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

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.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
): Promise<object>

chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

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

chrome.i18n.getUILanguage(): string