Localización de JavaScript con jQuery.i18n

A free translation by Chema, a Spain-based translator specializing in English to Spanish software translations

An original text written by Wai Foong, originally published in
https://betterprogramming.pub/how-to-do-javascript-localization-with-jquery-i18n-1320ff5d7a4e

* * *

Una biblioteca de internacionalización de JavaScript basada en jQuery

Este artículo trata sobre los pasos necesarios para localizar una página web a través de un framework de JavaScript llamado jQuery.i18n. Según lo que dice su página de GitHub:

jQuery.i18n es una biblioteca de internacionalización de JavaScript basada en jQuery. Te ayuda a internacionalizar tus aplicaciones web de forma sencilla.

Este es un proyecto del equipo de ingeniería de idiomas de la fundación Wikimedia y se utiliza en algunos de sus proyectos, como Universal Language Selector.

La biblioteca jquery.i18n utiliza un formato de archivo de localización basado en JSON llamado “banana”, que se utiliza como formato de archivo de localización para MediaWiki y otros proyectos.

Echemos un vistazo al siguiente ejemplo para saber más sobre cómo localizar el contenido de una aplicación web sin que se tenga que volver a cargar.

Hay cuatro apartados en este artículo:

1. Configuración
2. Formato de archivo de mensaje
3. Uso principal
4. Conclusión

1. Configuración

Crearemos una carpeta en el directorio raíz de nuestra aplicación web, y la llamaremosjquery.i18n. Allí incluiremos luego todos los archivos JavaScript necesarios. Podemos hacerlo de varias maneras: se pueden clonar los archivos git o simplemente guardar los archivos necesarios uno por uno desde la carpeta GitHub.

Clonar (método 1)

Abrimos el terminal Git y ejecutamos lo siguiente:

git clone https://github.com/wikimedia/jquery.i18n.git

Descargar zip (método 2)

Se puede descargar como un archivo zip desde la página oficial de GitHub.

Archivos JavaScript i18n

Vamos a la carpeta src, y copiamos los siguientes archivos a la carpeta jquery.i18n (excepto languages):

1. jquery.i18n.emitter.bidi.js
2. jquery.i18n.emitter.js
3. jquery.i18n.fallbacks.js
4. jquery.i18n.js
5. jquery.i18n.language.js
6. jquery.i18n.messagestore.js
7. jquery.i18n.parser.js

CLDRPluralRuleParser

Vamos a la carpeta libs/ CLDRPLuralRuleParser /src, y copiamos el siguiente archivo en la carpeta jquery.i18n:

1. CLDRPluralRuleParser.js

jQuery

Esta biblioteca se basa en jQuery y se recomienda utilizar su última versión. Iremos al siguiente enlace y descargaremos la versión que queramos. Yo usaré la versión minificada 3.4.1.

Archivos de idiomas

Crearemos una carpeta languages en el mismo directorio, donde luego meteremos los archivos de los diferentes idiomas.

La carpeta jquery.i18ndebería contener los siguientes archivos:

2. Formato de archivo de mensaje

Todos los archivos de idioma se basarán en el formato de archivo JSON. Se recomienda utilizar el código de idioma en el nombre de cada archivo de idioma o de configuración regional. Por ejemplo:

• Inglés: en.json
• Japonés: ja.json
• Chino: zh.json

Vamos a crear un archivo JSON simple usando la siguiente plantilla:

{
 "@metadata": {
 "authors": [
 "Wai Foong"
 ],
 "last-updated": "2019-10-10",
 "locale": "en",
 "other-metadata": "sample json format"
 },
 "appname-title": "Javascript Localization via jQuery.i18n",
 "appname-sub-title": "A jQuery based Javascript internationalization library.",
 "appname-introduction": "Introduction"
} 

La etiqueta de metadatos se utiliza para almacenar datos que no son mensajes y que sirven como referencias o información de lectura. La página oficial recomienda lo siguiente:

Los mensajes son pares clave-valor. Es aconsejable prefijar las claves como appname para que los mensajes sean únicos. Es el espacio donde pondremos el nombre para indicar las claves del mensaje. También es recomendable separar las claves con guiones, todo en minúsculas.

El archivo debe ser un JSON válido. Se tiene que evitar el uso de comillas simples cuando se esté trabajando con pares clave-valor. Puedes consultar más ejemplos de archivos JSON válidos en este repositorio.

3. Uso principal

La localización se puede realizar fácilmente utilizando el código JavaScript personalizado o la API de datos definida a través de la etiqueta HTML.

Puesta en marcha

Debemos vincular los archivos JavaScript a la página HTML de la aplicación web. Este es un ejemplo de cómo lo hice yo en mi proyecto.

<script src="path/jquery.i18n/jquery-3.4.1.min.js"></script>
<script src="path/jquery.i18n/CLDRPluralRuleParser.js"></script>
<script src="path/jquery.i18n/jquery.i18n.js"></script>
<script src="path/jquery.i18n/jquery.i18n.messagestore.js"></script>
<script src="path/jquery.i18n/jquery.i18n.fallbacks.js"></script>
<script src="path/jquery.i18n/jquery.i18n.language.js"></script>
<script src="path/jquery.i18n/jquery.i18n.parser.js"></script>
<script src="path/jquery.i18n/jquery.i18n.emitter.js"></script>
<script src="path/jquery.i18n/jquery.i18n.emitter.bidi.js"></script> 

Locale

En primer lugar, deberemos definir la configuración regional, ya que el mensaje que se va a mostrar se basará en este parámetro. Se puede definir fácilmente usando este código:

$.i18n( { 
     locale: 'en' // Locale is English 
});

Si no hemos definido la configuración regional, el framework se basará en el código de idioma proporcionado por la etiqueta HTML.

<html lang="es">

¿Y si ninguno de estos dos se especifica? Lo último que podemos hacer es utilizar la configuración regional que introduce el propio navegador. Podremos cambiar la configuración regional con la siguiente función:

 $.i18n().locale = 'ja'; //Switching locale to Japanese 

Carga de archivos

Hay bastantes formas de cargar archivos de idioma en formato JSON. Se pueden cargar por partes, pero la forma más fácil de hacerlo es desde una URL externa, de la siguiente manera:

$.i18n().load( {
 en: {
 'message-hello': 'Hello World',
 'message-goodbye': 'Good bye' },
 ja: 'i18n/messages-ja.json', // Messages for Japanese
 zh: 'i18n/messages-zh.json' // Messages for Chinese
} ); 

Es importante acordarse de editar el archivo de idioma y agregarle message-helloy message-goodbye.

API de datos

El código básico para mostrar el mensaje es el siguiente:

 <li data-i18n="message-hello"></li> 

Para mostrarlo sin código JavaScript, debemos agregarle el atributo data-i18n con un valor que actúe como clave de mensaje.

<li data-i18n="mensaje-hola"></li>

Podemos especificar un texto alternativo en caso de que message-hello no aparezca como clave en los archivos JSON que hemos cargado.

<li data-i18n="message-hello">Fallback text here!</li> 

Marcadores de posición

Los mensajes pueden tener marcadores de posición, que se representan mediante el signo del dólar (por ejemplo, $1, $2, $3, etc.). Serán reemplazados en el momento de la ejecución.

 var message = "Welcome to Medium, $1";
$.i18n(message, 'Wai Foong'); // "Welcome to Medium, Wai Foong" 

Podemos especificar más de un marcador de posición introduciendo más parámetros en la función.

 var message = "Welcome to $1, $2";
$.i18n(message, 'Medium', 'Wai Foong'); // "Welcome to Medium, Wai Foong" 

Plurales

Este framework  admite formas plurales en el mensaje a través de la siguiente fórmula: {{PLURAL:$1|pluralform1|pluralform2|...}}

Hay que tener en cuenta que PLURALno distingue entre mayúsculas y minúsculas. Todas las formas plurales se pueden indicar en la fórmula anterior, separadas por un símbolo de barra vertical.

Las reglas para cada idioma se definen en el archivo CLDRPluralRuleParser.js. El siguiente es un ejemplo de cómo puede mostrar diferentes mensajes según el recuento de elementos:

var message = 'Box has {{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}.';
$.i18n(message, 1); // "Box has one egg."
$.i18n(message, 6); // "Box has 6 eggs."
$.i18n(message, 12 ); // "Box has a dozen eggs." 

Género

Las formas para el género son similares a las formas para los plurales y se pueden usar para mostrar un mensaje basado en el género del contexto:

 var message = "$1 edited {{GENDER:$2|his|her}} article";
$.i18n(message, 'Amy', 'female' ); "Amy edited her article"
$.i18n(message, 'Bob', 'male' ); "Bob edited his article" 

4. Conclusión

¿Qué hemos aprendido? Comenzamos con una introducción básica a la biblioteca de internacionalización y luego continuamos explicando cómo configurar y crear los archivos y carpetas necesarios.

Después aprendimos sobre el formato de mensaje que se necesita para crear cada archivo de idioma. Debe ser un archivo con formato JSON válido y se recomienda mucho ponerle al nombre el código de idioma.

Finalmente, hablamos de las fórmulas, el uso principal y las formas adecuadas de utilizar esta biblioteca de internacionalización, que abarca unas funcionalidades muy útiles para trabajar luego con localización.

Gracias por leer el artículo, ¡espero verte de nuevo en el próximo! ¡Que tengas un buen día!

Referencias

1. https://github.com/wikimedia/jquery.i18n
2. https://phrase.com/blog/posts/step-step-guide-javascript-localization/
3. https://thottingal.in/projects/js/jquery.i18n/demo/
4. https://github.com/wikimedia/mediawiki/tree/master/languages/i18n