Documentación

Configuración Inicial

Comience agregando el paquete de localización de Angular a su proyecto:

ng add @angular/localize

Este comando realizará los siguientes cambios:

  • Agrega el paquete @angular/localize a tus dependencias
  • Agrega "@angular/localize/init" al array de polyfills en angular.json
  • Agrega la siguiente referencia a tu main.ts:
/// <reference types="@angular/localize" />

También se añadirá la configuración extract-i18n a angular.json:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Nota: Modificaremos el outputPath más adelante en la configuración para que coincida con nuestro flujo de trabajo.

Angular i18n CLI Tool

To simplify the management of Angular i18n configuration, you can use our CLI tool:

npm install --save-dev @softwarity/angular-i18n-cli

This tool provides several features to streamline your i18n workflow:

  • Easy initialization of i18n configuration in your Angular project
  • Simple addition and removal of locales
  • Automatic configuration of build settings for each locale
  • Proper setup of XLIFF file formats

Angular i18n CLI

CLI tool to simplify Angular i18n configuration and locale management.

Instalar Herramienta de Traducción

Para gestionar archivos de traducción, utilizaremos ng-extract-i18n-merge, que simplifica el proceso de extracción y fusión de traducciones:

npm install --save-dev ng-extract-i18n-merge

Esta herramienta ofrece varias ventajas:

  • Extrae automáticamente cadenas traducibles de tu aplicación
  • Fusiona nuevas traducciones con las existentes en un solo paso
  • Preserva las traducciones existentes durante las actualizaciones
  • Soporta múltiples idiomas de destino

Archivos de configuración

package.json

"scripts": {
  ...
  "extract-i18n": "ng extract-i18n",
  "build": "ng build --localize"
  ...
}

angular.json

Actualiza la configuración de i18n en angular.json:

"i18n": {
  "sourceLocale": "en",
  "locales": {
    "fr": {
      "translation": "src/locale/messages.fr.xlf"
    },
    "vi": {
      "translation": "src/locale/messages.vi.xlf"
    }
  }
},

Luego reemplace la configuración estándar de extract-i18n con ng-extract-i18n-merge:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Opciones de configuración importantes:

  • buildTarget: El nombre del objetivo de construcción de su aplicación
  • rutaDeSalida: Directorio donde se almacenarán los archivos de traducción
  • includeContext: Incluye información del archivo fuente en los archivos XLIFF
  • restablecerEstadoDeTraducción: Marca todas las traducciones como necesarias para revisión en caso de cambios
  • targetFiles: Lista de archivos de traducción a generar/actualizar

Build configurations

Agregue configuraciones para cada idioma en la sección de compilación:

"architect": {
  "build": {
    "configurations": {
      "fr": {
        "localize": ["fr"]
      },
      "vi": {
        "localize": ["vi"]
      }
    }
  }
}

Preparar Componentes para Traducción

Para preparar tus componentes para su traducción, necesitas marcar el texto que debe ser traducido. Angular proporciona dos formas de hacer esto:

Documentación de Angular: Marcado de texto para traducción

Aprende más sobre cómo preparar tu aplicación para la traducción.

Translation de Plantilla

Utiliza el atributo i18n en tus plantillas para marcar el texto para su traducción:

<tag attribute="This is a sample attribute text that needs translation." 
  i18n-attribute="@@ATTRIBUTE_TEXT"
  i18n="@@TAG_TEXT">This is a sample text that needs translation.</tag>
// EXAMPLE
<button title="Title button" i18n-title="@@TITLE_BUTTON"i18n="@@LABEL_BUTTON">label button</button>

El @@prefix define un ID personalizado para la traducción. Se recomienda utilizar SNAKE_CASE para mantener la consistencia.

Traducción de Componentes

Para el texto en el código de su componente, utilice la etiqueta de plantilla $localize:

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: '...'
})
export class ExampleComponent {
  title = $localize`:@@PAGE_TITLE:Welcome to our application`;
  errorMessage = $localize`:@@ERROR_MESSAGE:An error occurred while processing your request`;
}

Construcción y servicio

Construir con traducciones

Construya su aplicación con todas las traducciones:

npm run build

O construya para un idioma específico (usando el francés como ejemplo):

ng build --configuration=fr

Servidor de Desarrollo

Sirve tu aplicación con traducciones durante el desarrollo:

ng serve --configuration=fr

⚠️ Nota Importante

Después de añadir nuevo contenido traducible o modificar las traducciones existentes:

  1. ng extract-i18n - para extraer y actualizar todos los archivos de traducción en un solo paso

Este flujo de trabajo simplificado garantiza que sus archivos de traducción estén siempre actualizados con el contenido fuente, haciendo que el proceso de internacionalización sea más eficiente y libre de errores.