Traduce tu sitio web Angular 19 (Webpack) usando Intlayer | Internacionalización (i18n)

Tabla de contenidos

¿Qué es Intlayer?

Intlayer es una biblioteca de internacionalización (i18n) innovadora y de código abierto diseñada para simplificar el soporte multilingüe en aplicaciones web modernas.

Con Intlayer, puedes:

• Gestionar traducciones fácilmente utilizando diccionarios declarativos a nivel de componente.
• Localizar dinámicamente metadatados, rutas y contenido.
• Garantizar el soporte de TypeScript con tipos autogenerados, mejorando el autocompletado y la detección de errores.
• Beneficiarte de funciones avanzadas, como la detección y el cambio dinámico de idioma.

Guía paso a paso para configurar Intlayer en una aplicación Angular

Ver Plantilla de aplicación en GitHub.

Paso 1: Instalar dependencias

Instala los paquetes necesarios usando npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-webpack --save-devnpx intlayer init

• intlayer

  El paquete principal que proporciona herramientas de internacionalización para la gestión de la configuración, traducción, declaración de contenido, transpilación y comandos CLI.

• angular-intlayer El paquete que integra Intlayer con la aplicación Angular. Proporciona proveedores de contexto y hooks para la internacionalización de Angular.

• @angular-builders/custom-webpack Necesario para personalizar la configuración de Webpack de Angular CLI.

Paso 2: Configuración de tu proyecto

Crea un archivo de configuración para configurar los idiomas de tu aplicación:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Tus otros idiomas
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

A través de este archivo de configuración, puedes configurar URLs localizadas, redirección de middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los registros de Intlayer en la consola y más. Para obtener una lista completa de los parámetros disponibles, consulta la documentación de configuración.

Paso 3: Integrar Intlayer en tu configuración de Angular

Para integrar Intlayer con Angular CLI, necesitas usar un constructor (builder) personalizado. Esta guía asume que estás usando Webpack (predeterminado para muchos proyectos de Angular).

Primero, modifica tu angular.json para usar el constructor de Webpack personalizado. Actualiza las configuraciones de build y serve:

{  "projects": {    "nombre-de-tu-app": {      "architect": {        "build": {          "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",          "options": {            "customWebpackConfig": {              "path": "./webpack.config.ts",              "mergeStrategies": { "module.rules": "prepend" },            },            "main": "src/main.ts", // replace "browser": "src/main.ts",            // ...          },        },      },    },  },}

Asegúrate de reemplazar nombre-de-tu-app con el nombre real de tu proyecto en angular.json.

A continuación, crea un archivo webpack.config.ts en la raíz de tu proyecto:

import { mergeConfig } from "angular-intlayer/webpack";export default mergeConfig({});

La función mergeConfig configura Webpack con Intlayer. Inyecta el IntlayerPlugin (para manejar archivos de declaración de contenido) y configura alias para un rendimiento óptimo.

Paso 4: Declarar tu contenido

Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

Tus declaraciones de contenido pueden definirse en cualquier lugar de tu aplicación siempre que estén incluidas en el directorio contentDir (por defecto, ./src) y coincidan con la extensión de archivo de declaración de contenido (por defecto, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Para más detalles, consulta la documentación de declaración de contenido.

Paso 5: Utilizar Intlayer en tu código

Para utilizar las funciones de internacionalización de Intlayer en toda tu aplicación Angular, necesitas proporcionar Intlayer en la configuración de tu aplicación.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Añade el proveedor de Intlayer aquí  ],};

Luego, puedes usar la función useIntlayer dentro de cualquier componente.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Y en tu plantilla (template):

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

El contenido de Intlayer se devuelve como un Signal, por lo que accedes a los valores llamando al signal: content().title.

(Opcional) Paso 6: Cambiar el idioma de tu contenido

Para cambiar el idioma de tu contenido, puedes usar la función setLocale proporcionada por la función useLocale. Esto te permite establecer la ubicación de la aplicación y actualizar el contenido en consecuencia.

Crea un componente para cambiar entre idiomas:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

Luego, usa este componente en tu app.component.ts:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Configurar TypeScript

Intlayer utiliza el aumento de módulos para obtener los beneficios de TypeScript y fortalecer tu base de código.

Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.

{  // ... Tus configuraciones de TypeScript existentes  "include": [    // ... Tus configuraciones de TypeScript existentes    ".intlayer/**/*.ts", // Incluir los tipos autogenerados  ],}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar subirlos a tu repositorio de Git.

Para hacer esto, puedes añadir las siguientes instrucciones a tu archivo .gitignore:

#  Ignorar los archivos generados por Intlayer.intlayer

Extensión de VS Code

Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la extensión oficial Intlayer VS Code Extension.

Instalar desde el VS Code Marketplace

Esta extensión proporciona:

• Autocompletado para las claves de traducción.
• Detección de errores en tiempo real para traducciones faltantes.
• Vistas previas integradas del contenido traducido.
• Acciones rápidas para crear y actualizar traducciones fácilmente.

Para más detalles sobre cómo usar la extensión, consulta la documentación de la extensión Intlayer VS Code.

Ir más allá

Para ir más allá, puedes implementar el editor visual o externalizar tu contenido usando el CMS.