Comenzando con la internacionalización (i18n) usando Intlayer y Nuxt

Consulta la Plantilla de Aplicación en GitHub.

¿Qué es Intlayer?

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

Con Intlayer, puedes:

• Gestionar traducciones fácilmente usando diccionarios declarativos a nivel de componente.
• Localizar dinámicamente metadatos, rutas y contenido.
• Garantizar soporte para TypeScript con tipos autogenerados, mejorando la autocompletación 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 Nuxt

Paso 1: Instalar dependencias

Instala los paquetes necesarios usando npm:

npm install intlayer vue-intlayernpm install --save-dev nuxt-intlayer

• intlayer

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

• vue-intlayer El paquete que integra Intlayer con aplicaciones Vue. Proporciona los composables para los componentes Vue.

• nuxt-intlayer El módulo de Nuxt que integra Intlayer con aplicaciones Nuxt. Proporciona configuración automática, middleware para la detección de la configuración regional, gestión de cookies y redirección de URL.

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 locales    ],    defaultLocale: Locales.ENGLISH,  },  content: {    contentDir: ["."], // Porque por defecto Intlayer observará los archivos de declaración de contenido desde el directorio `./src`  },};export default config;

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

Paso 3: Integra Intlayer en tu configuración de Nuxt

Agrega el módulo intlayer a tu configuración de Nuxt:

import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Tu configuración existente de Nuxt  modules: ["nuxt-intlayer"],});

El módulo nuxt-intlayer maneja automáticamente la integración de Intlayer con Nuxt. Configura la construcción de la declaración de contenido, monitorea los archivos en modo desarrollo, proporciona middleware para la detección de la localidad y gestiona el enrutamiento localizado.

Paso 4: Declara Tu Contenido

Crea y administra tus declaraciones de contenido para almacenar traducciones:

import { t, type Dictionary } from "intlayer";const helloWorldContent = {  key: "helloworld",  content: {    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),    edit: t({      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",    }),    checkOut: t({ en: "Check out ", fr: "Vérifiez ", es: "Compruebe " }),    nuxtIntlayer: t({      en: "Nuxt Intlayer documentation",      fr: "Documentation de Nuxt Intlayer",      es: "Documentación de Nuxt Intlayer",    }),    learnMore: t({      en: "Learn more about Nuxt in the ",      fr: "En savoir plus sur Nuxt dans la ",      es: "Aprenda más sobre Nuxt en la ",    }),    nuxtDocs: t({      en: "Nuxt Documentation",      fr: "Documentation Nuxt",      es: "Documentación de Nuxt",    }),    readTheDocs: t({      en: "Click on the Nuxt logo to learn more",      fr: "Cliquez sur le logo Nuxt pour en savoir plus",      es: "Haga clic en el logotipo de Nuxt para obtener más información",    }),  },} satisfies Dictionary;export default helloWorldContent;      fr: "Cliquez sur le logo Nuxt pour en savoir plus",      es: "Haga clic en el logotipo de Nuxt para obtener más información",    }),  },} satisfies Dictionary;export default helloWorldContent;

Sus declaraciones de contenido pueden definirse en cualquier lugar de su 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,mjx,cjs,cjx}).

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

Paso 5: Utilice Intlayer en su Código

Acceda a sus diccionarios de contenido en toda su aplicación Nuxt usando el composable useIntlayer:

<script setup lang="ts">import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const {  count,  edit,  checkOut,  nuxtIntlayer,  learnMore,  nuxtDocs,  readTheDocs,} = useIntlayer("helloworld");const countRef = ref(0);</script><template>  <h1>{{ msg }}</h1>  <div class="card">    <button type="button" @click="countRef++">      <count />      {{ countRef }}    </button>    <p v-html="edit"></p>  </div>  <p>    <checkOut />    <a href="https://nuxt.com/docs/getting-started/introduction" target="_blank"      >Nuxt</a    >, <nuxtIntlayer />  </p>  <p>    <learnMore />    <a href="https://nuxt.com" target="_blank"><nuxtDocs /></a>.  </p>  <p class="read-the-docs"><readTheDocs /></p>  <p class="read-the-docs">{{ readTheDocs }}</p></template>

Accediendo al Contenido en Intlayer

Intlayer ofrece diferentes APIs para acceder a tu contenido:

• Sintaxis basada en componentes (recomendada): Usa la sintaxis <myContent /> o <Component :is="myContent" /> para renderizar contenido como un Nodo de Intlayer. Esto se integra perfectamente con el Editor Visual y el CMS.

• Sintaxis basada en cadenas: Usa {{ myContent }} para renderizar el contenido como texto plano, sin soporte para el Editor Visual.

• Sintaxis HTML sin procesar: Usa <div v-html="myContent" /> para renderizar el contenido como HTML sin procesar, sin soporte para el Editor Visual.

• Sintaxis de desestructuración: El composable useIntlayer devuelve un Proxy con el contenido. Este proxy puede ser desestructurado para acceder al contenido manteniendo la reactividad.
• Usa const content = useIntlayer("myContent"); y {{ content.myContent }} / <content.myContent />.
• O usa const { myContent } = useIntlayer("myContent"); y {{ myContent}} / <myContent/> para desestructurar el contenido.

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

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

Crea un componente para cambiar entre idiomas:

<template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup lang="ts">import { ref, watch } from "vue";import { getLocaleName } from "intlayer";import { useLocale } from "vue-intlayer";// Obtener información del locale y la función setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Rastrear el locale seleccionado con un refconst selectedLocale = ref(locale.value);// Actualizar el locale cuando cambia la selecciónconst changeLocale = () => setLocale(selectedLocale.value);// Mantener selectedLocale sincronizado con el locale globalwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script></template><style scoped>.locale-switcher {  margin: 1rem 0;}select {  padding: 0.5rem;  border-radius: 0.25rem;  border: 1px solid #ccc;}</style>

Luego, usa este componente en tus páginas o en el layout:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";const content = useIntlayer("app"); // Crear archivo de declaración intlayer relacionado</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <NuxtPage />    </main>  </div></template>

(Opcional) Paso 7: Añadir enrutamiento localizado a tu aplicación

Nuxt maneja automáticamente el enrutamiento localizado cuando se utiliza el módulo nuxt-intlayer. Esto crea rutas para cada idioma automáticamente basándose en la estructura del directorio de tus páginas.

Ejemplo:

pages/├── index.vue          → /, /fr, /es├── about.vue          → /about, /fr/about, /es/about└── contact/    └── index.vue      → /contact, /fr/contact, /es/contact

Para crear una página localizada, simplemente crea tus archivos Vue en el directorio pages/:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about");</script><template>  <div>    <h1>{{ content.title }}</h1>    <p>{{ content.description }}</p>  </div></template>

El módulo nuxt-intlayer automáticamente:

• Detectar el idioma preferido del usuario
• Gestionar el cambio de idioma a través de la URL
• Establecer el atributo <html lang=""> apropiado
• Administrar las cookies de idioma
• Redirigir a los usuarios a la URL localizada correspondiente

(Opcional) Paso 8: Crear un Componente de Enlace Localizado

Para asegurar que la navegación de tu aplicación respete el idioma actual, puedes crear un componente personalizado LocalizedLink. Este componente añade automáticamente el prefijo del idioma actual a las URLs internas.

<template>  <NuxtLink :to="localizedHref" v-bind="$attrs">    <slot />  </NuxtLink></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: String,    required: true,  },});const { locale } = useLocale();// Verificar si el enlace es externoconst isExternalLink = computed(() => /^https?:\/\//.test(props.to || ""));// Crear un href localizado para enlaces internosconst localizedHref = computed(() =>  isExternalLink.value ? props.to : getLocalizedUrl(props.to, locale.value));</script>

Luego usa este componente en toda tu aplicación:

<template>  <div>    <LocalizedLink to="/about">      {{ content.aboutLink }}    </LocalizedLink>    <LocalizedLink to="/contact">      {{ content.contactLink }}    </LocalizedLink>  </div></template><script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocalizedLink from "~/components/LocalizedLink.vue";const content = useIntlayer("home");</script>

(Opcional) Paso 9: Manejar Metadatos y SEO

Nuxt ofrece excelentes capacidades de SEO. Puedes usar Intlayer para manejar metadatos localizados:

<script setup lang="ts">import { useSeoMeta } from "nuxt/app";import { getIntlayer } from "intlayer";import { useLocale } from "vue-intlayer";const { locale } = useLocale();const content = getIntlayer("about-meta", locale.value);useSeoMeta({  title: content.title,  description: content.description,});</script><template>  <div>    <h1>{{ content.pageTitle }}</h1>    <p>{{ content.pageContent }}</p>  </div></template>

Crea la declaración de contenido correspondiente:

import { t, type Dictionary } from "intlayer";import type { useSeoMeta } from "nuxt/app";const aboutMetaContent = {  key: "about-meta",  content: {    title: t({      en: "About Us - My Company",      fr: "À Propos - Ma Société",      es: "Acerca de Nosotros - Mi Empresa",    }),    description: t({      en: "Learn more about our company and our mission",      fr: "En savoir plus sur notre société et notre mission",      es: "Conozca más sobre nuestra empresa y nuestra misión",    }),  },} satisfies Dictionary<Parameters<typeof useSeoMeta>[0]>;export default aboutMetaContent;

Configurar TypeScript

Intlayer utiliza la ampliación de módulos para aprovechar las ventajas de TypeScript y fortalecer su base de código.

Asegúrese de que su configuración de TypeScript incluya los tipos autogenerados.

{  // ... Sus configuraciones existentes de TypeScript  "include": [    // ... Tus configuraciones existentes de TypeScript    ".intlayer/**/*.ts", // Incluir los tipos generados automáticamente  ],}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar comprometerlos en tu repositorio Git.

Para hacerlo, puedes agregar 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 traducciones 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, consulte la documentación de la extensión Intlayer para VS Code.

Ir más allá

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

Historial del documento

• 5.5.10 - 2025-06-29: Historial inicial