Cómo utilizar la internacionalización (i18n) en Angular

Introducción

La internacionalización es el proceso de admitir varios idiomas en sus aplicaciones.

Esto se puede lograr en una aplicación Angular a través de bibliotecas de terceros, como ngx-translate, o puede utilizar la funcionalidad i18n incorporada.

Nota: “i18n” es un numerónimo donde “18” representa la cantidad de letras entre la primera letra (“I”) y la última letra (“N”) en la palabra “internacionalización”. A medida que desarrolle aplicaciones, también puede encontrarse con “a11y”, que es un numerónimo de accesibilidad.

En este tutorial, aprenderá a utilizar la funcionalidad i18n incorporada en una aplicación Angular.

Prerrequisitos

Para completar este tutorial, necesitarás:

• Node.js instalado localmente, lo cual puedes hacer siguiendo Cómo instalar Node.js y crear un entorno de desarrollo local .
• Puede resultar beneficioso tener cierta familiaridad con la configuración de un proyecto Angular y el uso de componentes Angular .

Este tutorial fue verificado con Node v14.13.1, npmv6.14.8, angularv10.1.6 y @angular/localizev10.1.6.

Paso 1: Configuración del proyecto

Puedes usarlo @angular/clipara crear un nuevo proyecto Angular.

En su ventana de terminal, utilice el siguiente comando:

npx @angular/cli new angular-internationalization-example --style=css --routing=false --skip-tests

Esto configurará un nuevo proyecto Angular con estilos establecidos en “CSS” (a diferencia de “Sass”, Less” o “Stylus”), sin enrutamiento y sin omitir pruebas.

Navegue hasta el directorio del proyecto recién creado:

cd angular-internationalization-example

Para crear la base para el proyecto de traducción, abra app.component.htmlsu editor de código y reemplace el código con las siguientes líneas:

src/aplicación/aplicación.componente.html

section  article    h1Under Construction!/h1    pThis page is under construction./p  /article/section

Este código mostrará "Under Construction!"y "This page is under construction"mensajes.

A continuación, abra app.component.cssy reemplace el código con las siguientes líneas:

sec/app/app.component.css

section {  background: #8e2de2; /* fallback for old browsers */  background: -webkit-linear-gradient(to right, #4a00e0, #8e2de2); /* Chrome 10-25, Safari 5.1-6 */  background: linear-gradient(to right, #4a00e0, #8e2de2);  display: flex;  justify-content: center;  align-items: center;  height: 100vh;}article {  border: 1px solid white;  box-shadow: 1px 1px 100px 10px rgba(0, 0, 0, 0.8);  color: white;  padding: 40px;  text-align: center;}

Este código utiliza flexbox, valores de altura de ventana gráfica, fondos con degradado lineal y sombras de cuadro para centrar el "Under Construction!"mensaje en la pantalla.

Luego, abra styles.cssy reemplace el código con las siguientes líneas:

src/estilos.css

html,body {  padding: 0;  margin: 0;}

Esto eliminará cualquier relleno y margen que los estilos de usuario del navegador tienden a colocar de forma predeterminada. Al usar estos estilos, puede crear una línea de base consistente entre todos los navegadores con diferentes valores predeterminados.

En una ventana de terminal, inicie su aplicación:

npm start

Visita localhost:4200en tu navegador web:

Una vez que pueda verificar que la aplicación se comporta como se espera, puede comenzar a extraer los mensajes que desea traducir.

Paso 2: Uso xi18npara extraermessages.xlf

Comencemos marcando el texto que desea traducir dentro de la aplicación. En este tutorial, traducirá la aplicación al francés ( fr) y al alemán ( de) y Google Translate proporcionará las traducciones.

Añade la i18ndirectiva a todo el texto que quieras traducir:

src/aplicación/aplicación.componente.html

section  article    h1 i18nUnder Construction!/h1    p i18nThis page is under construction./p  /article/section

Luego, tendrás que crear un script npm dentro package.jsonque use la CLI de Angular para extraer los elementos marcados en app.component.htmlun messages.xlfarchivo:

paquete.json

{  // ...  "scripts": {    "ng": "ng",    "start": "ng serve",    "build": "ng build",    "test": "ng test",    "lint": "ng lint",    "e2e": "ng e2e",    "i18n:extract": "ng xi18n"  },  // ...}

Después de agregar esto, ejecute su nuevo script en una ventana de terminal:

npm run i18n:extract

Luego, abre messages.xlfy observarás algo similar a esto:

mensajes.xlf

?xml version="1.0" encoding="UTF-8" ?xliff version="1.2"   file source-language="en-US" datatype="plaintext" original="ng2.template"    body      trans-unit datatype="html"        sourceUnder Construction!/source        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"3/context        /context-group      /trans-unit      trans-unit datatype="html"        sourceThis page is under construction./source        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"4/context        /context-group      /trans-unit    /body  /file/xliff

Para cada elemento que necesite traducción (es decir, que tenga la i18ndirectiva), trans-unitse creará un .

También puedes usar esta estructura para brindar más información sobre la traducción. Esto es útil si recibes cada mensaje traducido por un tercero y deseas brindar más información.

Dentro de app.component.html, actualiza los i18nelementos con una descripción :

src/aplicación/aplicación.componente.html

article  h1 i18n="Title for the under construction card"Under Construction!/h1  p i18n="A description for the under construction card."This page is under construction./p/article

Puede agregar más contexto a esto utilizando el carácter de barra vertical ( |). Esto le da un significado a un elemento y cada elemento con el mismo significado tendrá la misma traducción:

src/aplicación/aplicación.componente.html

article  h1 i18n="Card Header|Title for the under construction card"Under Construction!/h1  p i18n="Card Descritpion|A description for the under construction card."This page is under construction./p/article

También puedes darle a cada i18nelemento un id usando dos caracteres de símbolo arroba ( @@) para forzar la persistencia al generar las traducciones:

src/aplicación/aplicación.componente.html

article  h1 i18n="Card Header|Title for the under construction card@@constructionHeader"Under Construction!/h1  p i18n="Card Descritpion|A description for the under construction card.@@constructionDescription"This page is under construction./p/article

Construyamos las traducciones una vez más:

npm run int:extract

Los elementos ahora se actualizarán con la identificación , el significado y la descripción :

mensajes.xlf

?xml version="1.0" encoding="UTF-8" ?xliff version="1.2"   file source-language="en-US" datatype="plaintext" original="ng2.template"    body      trans-unit datatype="html"        sourceUnder Construction!/source        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"3/context        /context-group        note priority="1" from="description"Title for the under construction card/note        note priority="1" from="meaning"Card Header/note      /trans-unit      trans-unit datatype="html"        sourceThis page is under construction./source        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"4/context        /context-group        note priority="1" from="description"A description for the under construction card./note        note priority="1" from="meaning"Card Descritpion/note      /trans-unit    /body  /file/xliff

Una vez que tenga un messages.xlfarchivo con múltiples trans-units, descripción, significado e id, puede comenzar a crear traducciones al francés y al alemán.

Paso 3: Creación de traducciones al francés y al alemán

De forma predeterminada, Angular considera que todo está en la en-USconfiguración regional “inglés americano” ( ). Deberá agregar otras configuraciones regionales y actualizar la configuración para que sean compatibles.

Se hace referencia a estas configuraciones regionales mediante identificadores regionales (ID). Por ejemplo, “inglés americano” utiliza el ID en-US. Los dos primeros caracteres – en– asignan un identificador regional para “inglés”. Los dos últimos caracteres – US– asignan una extensión regional para “Estados Unidos”. Estos identificadores se derivan de las reglas establecidas por BCP47 .

Para evitar saturar el directorio del proyecto, puede resultar beneficioso almacenar los archivos de traducción en un directorio nuevo. Puede proporcionar una output-pathopción a su i18n:extractscript para colocarlos en un localesdirectorio:

paquete.json

{  // ...  "scripts": {    "ng": "ng",    "start": "ng serve",    "build": "ng build",    "test": "ng test",    "lint": "ng lint",    "e2e": "ng e2e",    "i18n:extract": "ng xi18n --output-path src/locale"  },  // ...}

Eliminar el messages.xlfarchivo existente:

rm messages.xlf

Y vuelva a ejecutar el i18n:extractcomando;

npm run i18n:extract

Una vez que haya verificado que el cambio de script funciona como se espera y que hay un messages.xlfarchivo en el localesdirectorio, puede comenzar a agregar targets para las traducciones.

Francés

Primero, copia messages.xlfa messages.fr.xlf:

cp src/locale/messages.xlf src/locale/messages.fr.xlf

Luego, agrega un targetpara cada elemento:

src/locale/messages.fr.xlf

?xml version="1.0" encoding="UTF-8" ?xliff version="1.2"   file source-language="en-US" datatype="plaintext" original="ng2.template"    body      trans-unit datatype="html"        sourceUnder Construction!/source        targetEn construction/target        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"3/context        /context-group        note priority="1" from="description"Title for the under construction card/note        note priority="1" from="meaning"Card Header/note      /trans-unit      trans-unit datatype="html"        sourceThis page is under construction./source        targetCette page est en construction/target        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"4/context        /context-group        note priority="1" from="description"A description for the under construction card./note        note priority="1" from="meaning"Card Descritpion/note      /trans-unit    /body  /file/xliff

Cada uno trans-unittiene ahora un sourcemensaje en inglés y un targetmensaje en francés.

Alemán

A continuación, copie messages.xlfa messages.de.xlf:

cp src/locale/messages.xlf src/locale/messages.de.xlf

Luego, agrega un targetpara cada elemento:

src/locale/messages.de.xlf

?xml version="1.0" encoding="UTF-8" ?xliff version="1.2"   file source-language="en-US" datatype="plaintext" original="ng2.template"    body      trans-unit datatype="html"        sourceUnder Construction!/source        targetIm Bau/target        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"3/context        /context-group        note priority="1" from="description"Title for the under construction card/note        note priority="1" from="meaning"Card Header/note      /trans-unit      trans-unit datatype="html"        sourceThis page is under construction./source        targetDiese Seite befindet sich im Aufbau/target        context-group purpose="location"          context context-type="sourcefile"src/app/app.component.html/context          context context-type="linenumber"4/context        /context-group        note priority="1" from="description"A description for the under construction card./note        note priority="1" from="meaning"Card Descritpion/note      /trans-unit    /body  /file/xliff

Cada uno trans-unittiene ahora un sourcemensaje en inglés y un targetmensaje en alemán.

Paso 4: creación de compilaciones en francés y alemán

Tiene versiones de la aplicación que están traducidas en función de locale.

Puede utilizar la CLI de Angular para generar compilaciones específicas para cada configuración regional que desee admitir.

Primero, necesitarás instalar @angular/localize:

./node_modules/@angular/cli/bin/ng add @angular/localize

Ábrelo angular.jsonen tu editor de código y agrega frlas deconfiguraciones regionales:

angular.json

{  "projects": {    "angular-internationalization-example": {      // ...      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "baseHref": ""          },          "de": {            "translation": "src/locale/messages.de.xlf",            "baseHref": ""           }        }      },      "architect": {        // ...      }    }},  // ...}

Y crear ajustes de configuración para fry deen build:

angular.json

{  "projects": {    "angular-internationalization-example": {      // ...      "architect": {        "build": {          // ...          "configurations": {            "production": {              // ...            },            "fr": {              "localize": ["fr"],              "outputPath": "dist/under-construction-fr/",              "i18nMissingTranslation": "error"            },            "de": {              "localize": ["de"],              "outputPath": "dist/under-construction-de/",              "i18nMissingTranslation": "error"            }          }        },        // ...      }    }},  // ...}

Nota: Anteriormente, este tutorial utilizaba valores separados para "i18nFile", "i18nFormat"y ““i18nLocale” . These have since been deprecated and localize` es el enfoque preferido.

También puede actualizar la configuración en serve:

angular.json

{  "projects": {    "angular-internationalization-example": {      // ...      "architect": {        "serve": {          // ...          "configurations": {            "production": {              "browserTarget": "angular-internationalization-example:build:production"            },            "fr": {              "browserTarget": "angular-internationalization-example:build:fr"            },            "de": {              "browserTarget": "angular-internationalization-example:build:de"            }          }        },        // ...      }    }},  // ...}

Ahora puedes crear más scripts dentro de package.jsonlos cuales se incluye la capacidad de crear y servir los nuevos locales:

paquete.json

{  "scripts": {    "ng": "ng",    "start": "ng serve",    "start:fr": "ng serve --configuration=fr",    "start:de": "ng serve --configuration=de",    "build": "ng build",    "build:fr": "ng build --configuration=fr",    "build:de": "ng build --configuration=de",    "test": "ng test",    "lint": "ng lint",    "e2e": "ng e2e",    "i18n:extract": "ng xi18n --output-path src/locale"  }}

Puedes iniciar todos nuestros proyectos ejecutando lo siguiente en la terminal:

npm start

Y en otra ventana de terminal, inicie la compilación en francés:

npm run start:fr -- --port=4201

Y en otra ventana de terminal, inicie la compilación en alemán:

npm run start:de -- --port=4202

Esto ejecutará la aplicación en inglés en el puerto predeterminado, en francés en el puerto 4201 y en alemán en el puerto 4202:

Has creado versiones traducidas de tu aplicación.

Conclusión

En este tutorial, utilizó la herramienta i18n incorporada disponible en Angular para generar compilaciones traducidas en francés y alemán.

Para leer más sobre el uso de la herramienta i18n incorporada, consulte la documentación oficial .

Si desea obtener más información sobre Angular, consulte nuestra página de temas de Angular para ver ejercicios y proyectos de programación.