Traduce tu aplicación Analog (Angular) con Intlayer | Internacionalización (i18n)

Tabla de contenidos

¿Por qué Intlayer en lugar de alternativas?

En comparación con soluciones principales como ngx-translate o angular-l10n, Intlayer es una solución que viene con optimizaciones integradas como:

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

Ver Plantilla de Aplicación en GitHub.

1. 1

   Instalar dependencias

   Instala los paquetes necesarios usando npm:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npx intlayer init --interactive
   

   la bandera --interactive es opcional. Usa intlayer-cli init si eres un agente de IA.

   Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer angular-intlayer vite-intlayer
   

   • 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 de 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.

   • vite-intlayer El paquete que integra Intlayer con Vite. Proporciona un complemento para manejar archivos de declaración de contenido y establece alias para un rendimiento óptimo.

2. 2

   Configuración de tu proyecto

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

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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.

3. 3

   Integrar Intlayer en tu configuración de Vite

   Para integrar Intlayer con Analog, necesitas usar el complemento vite-intlayer.

   Modifica tu archivo vite.config.ts:

   vite.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import analog from "@analogjs/platform";
   
   // https://vitejs.dev/config/
   export default defineConfig(() => ({
     plugins: [
       analog(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   }));
   

   El complemento intlayer() configura Vite con Intlayer. Maneja los archivos de declaración de contenido y establece alias para un rendimiento óptimo.

4. 4

   Declarar tu contenido

   Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

   Tus declaraciones de contenido se pueden definir en cualquier lugar de tu aplicación, siempre que se incluyan en el directorio contentDir (por defecto, ./src). Y coincidan con la extensión del archivo de declaración de contenido (por defecto, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

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

5. 5

   Utilizar Intlayer en tu código

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

   src/app/app.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

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

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

   src/app/pages/index.page.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   
   @Component({
     selector: "app-home",
     standalone: true,
     template: `
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     content = useIntlayer("app");
   }
   

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

6. 6

   Cambiar el idioma de tu contenido

   Opcional

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

   Crea un componente para cambiar entre idiomas:

   src/app/locale-switcher.component.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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 tus páginas:

   src/app/pages/index.page.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   import { LocaleSwitcherComponent } from "../locale-switcher.component";
   
   @Component({
     selector: "app-home",
     standalone: true,
     imports: [LocaleSwitcherComponent],
     template: `
       <app-locale-switcher></app-locale-switcher>
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     content = useIntlayer("app");
   }
   

Configurar TypeScript

Intlayer utiliza la aumentación 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 de Intlayer para VS Code.

Instalar desde el Marketplace de VS Code

Esta extensión proporciona:

• Autocompletado para las claves de traducción.
• Detección de errores en tiempo real para traductions faltantes.
• Vistas previas en línea 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 de Intlayer para VS Code.

Ir más allá

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

Preguntas frecuentes