Integrar I18N de Nautilus

Introducción

Desde Nautilus se ha creado un conjunto de servicios que permiten a los desarrolladores de productos dar de alta literales para que posteriormente sean traducidos por los equipos de traducción de ABS.

Podemos ver como 4 las herramientas/servicios que da Nautilus para la integración de I18N:

App de alta de literales (https://literaladmin.nautilus.app/): Permite a los desarrolladores con permiso para ello a nivel de Nautilus el dar de alta los literales que aparecen en sus aplicaciones.
App gestión de traducciones (https://translator.nautilus.app/): Permite a los traductores introducir/modificar las traducciones para los literales que han introducido los desarrolladores.
API para consultar traducciones (https://api.nautilus.app/doc/#translate): En el API público hay una sección con endpoints que permiten consultar las traducciones de los literales.
Herramienta creación fichero literales (http://nexus2.absapp.net/ @platform-node-tools/translate-cli): Se ha publicado un herramienta Node.js en el Nexus de ABS que permite generar un fichero JSON con todos los literales en distintos idiomas de una aplicación para que de esta forma podamos tratarlo como un fichero más de nuestra solución software.

Cómo dar de alta nuevos literales

Para dar de alta nuevos literales, en primer lugar, tenemos que estar asignados como "desarrolladores" de Nautilus, para ello hay que solicitar permisos en support@nautilus.app. Después podremos acceder a https://literaladmin.nautilus.app/.

Desde esta aplicación se permite listar, añadir, editar y eliminar literales.

Los literales se componen de los siguientes elementos:

Producto
Servicio
Módulo, el apartado de la aplicación donde se usa el literal.
Código del literal
Contexto del literal, para qué se usa el literal
Traducción en lenguaje desarrollador, Traducción que le da el desarrollador temporalmente.

El Producto y el Servicio son necesarios para recuperar las traducciones desde el API de Nautilus. El módulo y contexto son esencialmente para ayudar en la tarea de los traductores.

Como muestra el siguiente vídeo, se pueden crear los literales de uno en uno o añadirlos en formato json de forma masiva.

Cómo consumir el servicio de I18N

Existen múltiples aproximaciones para consumir el servicio de traducciones. Y todas ellas tienen como punto común el servicio de consumo: https://api.nautilus.app/doc/ En este servicio encontrarás varios endpoints que te permitirar obtener las traducciones.

Tratar literales de forma dinámica

Como con otros servicios simplemente habría que consumir el servicio del API de Nautilus.

Como ventajas tiene que podemos cambiar las traducciones y añadir idiomas a tiempo real, sin necesidad de desplegar el proyecto, ya que las traducciones son tratadas como datos.

Como desventaja, se hacen más peticiones desde frontend al servicio de traducciones, lo que afecta en tiempos de carga más lentos. Además cualquier cambio de una traducción modificaría o incluso podría "romper" la aplicación frontend que lo consume. Por eso para desarrollos internos esta opción no está recomendada.

Tratar literales de forma estática (recomendado)

Recomendamos tratar los literales como código, se genera el fichero de literales en el pipeline de build del artefacto del proyecto frontend en el que estamos trabajando. De esta forma una vez se valida ese artefacto tanto a nivel funcional como de QA sabemos que para esa versión de nuestro software siempre se mostrarán las mismas traducciones, ya validadas. Para ello el pipeline usa el servicio de traducciones mediante nuestra herramienta translator-cli. Lo mismo podrán hacer los desarrolladores para trabajar en local.

Las ventajas principales son:

UI más rápido al no tener que esperar a recibir las traducciones.
Una vez revisada una aplicación se mostrará siempre igual a nivel de literales, siendo menos frágil.

Translate CLI

Se ha creado un CLI para automatizar la descarga de traducciones, está disponible en el npm registry del Nexus (http://nexus2.absapp.net/repository/npm-public, que debe estar en el fichero .npmrc del proyecto o en el fichero global en tu directorio de usuario). El CLI está en el paquete @platform-node-tools/translate-cli.

Mayormente se puede usar como un CLI desde consola o como tarea en los scripts del package.json, aunque se recomienda esto sólo para el desarrollo. Para el despliegue se recomienda habilitar una tarea para ello en el Jenkinsfile, se ha publicado una imagen de docker del CLI para su uso sin la necesidad de tener instalado Node.

El comando requiere seguir el siguiente formato:

translate -o <dirección del fichero> -f <formato> -s <fuente de las traducciones> -a <nombre de la aplicación> -t <tipo de aplicación>

Mayormente por defecto se genera un fichero con un objeto que tiene cada clave de campo como un lenguaje disponible y cada valor como un objeto con traducciones formadas por clave valor. Hay dos tipo de salida de ficheros, una que sólo genera un fichero con toda la información y otro que genera un fichero por cada lenguaje en el que el nombre del directorio será el especificado en el --output y cada fichero tendrá como nombre el lenguaje de las traducciones que contiene.

Si no hay traducción siempre tendrá por defecto el lenguaje del desarrollador.

En proyectos de Node.js, se suele instalar el CLI en las devDependencies y se habilita un script, npm run i18n, configurado consecuentemente para descargar las traducciones de ese proyecto.

javascript

 stage('Translations') {
            steps {
                script {
                    echo '_______________________ Translations _______________________'
                    def ws = pwd()
                    sh "docker run --rm -u ${currentUser} -v ${ws}:/data/app ${DOCKER_REGISTRY_URL}/cmd_translate:latest -o src/common/locales/memory -f es6 -s ${TRANSLATIONS} -a ${SERVICE_NAME} -t ${SERVICE_TYPE}"
                }
            }
        }

 stage('Translations') {
            steps {
                script {
                    echo '_______________________ Translations _______________________'
                    def ws = pwd()
                    sh "docker run --rm -u ${currentUser} -v ${ws}:/data/app ${DOCKER_REGISTRY_URL}/cmd_translate:latest -o src/common/locales/memory -f es6 -s ${TRANSLATIONS} -a ${SERVICE_NAME} -t ${SERVICE_TYPE}"
                }
            }
        }

La imagen de docker funciona exactamente igual que el CLI y debe ser configurado del mismo modo. Se encuentra en Docker Registry como dockerprivatehub-on.azurecr.io/cmd_translate

Cómo traducir literales

Para permitir a servicios lingüísticos la tarea de traducir los literales existentes en el servicio de traducción disponen de la aplicación web Rosetta.

https://translator.nautilus.app

Para acceder a la aplicación, servicios lingüísticos debe tener los usuarios registrados en Nautilus.

Desde la interfaz de Rosetta podemos hacer una exportación en formato xls de las traducciones, seleccionando:

Producto o conjunto de productos para los que se exportaran los literales
El idioma origen
Idiomas destino

Sobre ese mismo fichero se pueden reflejar cambios sobre la pestaña de 'IMPORTAR'.

Sobre el Excel original se deben añadir nuevas columnas a partir de la columna "F" indicando en la primera fila el idioma sobre el que se van a introducir los literales.

Una vez realizados los cambios podremos importar el fichero modificado. Rosetta nos devolverá el resultado de la importación en un fichero xls.

Integrar I18N de Nautilus ​

Introducción ​

Cómo dar de alta nuevos literales ​

Cómo consumir el servicio de I18N ​

Tratar literales de forma dinámica ​

Tratar literales de forma estática (recomendado) ​

Translate CLI ​

Cómo traducir literales ​