Traduce tu sitio web Nuxt y Vue usando Intlayer | Internacionalización (i18n)

Tabla de Contenidos

¿Qué es Intlayer?

Intlayer es una biblioteca innovadora y de código abierto para 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.
• Asegurar soporte para TypeScript con tipos autogenerados, mejorando la autocompletación y detección de errores.
• Beneficiarte de funciones avanzadas, como la detección y cambio dinámico de locales.

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

Consulta la Plantilla de Aplicación en GitHub.

Paso 1: Instalar Dependencias

Instala los paquetes necesarios usando npm:

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

• 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 locale, 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,
  },
};

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, desactivar 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 las declaraciones de contenido, monitorea los archivos en modo desarrollo, proporciona middleware para la detección de la locale y gestiona el enrutamiento localizado.

Paso 4: Declara tu Contenido

Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

Tus declaraciones de contenido pueden definirse en cualquier parte 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: Utiliza Intlayer en tu Código

Accede a tus diccionarios de contenido en toda tu 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 usando NuxtLink. Usar enlaces en lugar de botones para cambiar de idioma es una buena práctica para SEO y la descubribilidad de la página, ya que permite a los motores de búsqueda rastrear e indexar todas las versiones localizadas de tus páginas:

<script setup lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Nuxt importa automáticamente useRouteconst route = useRoute();const { locale, availableLocales, setLocale } = useLocale();</script><template>  <nav class="locale-switcher">    <NuxtLink      v-for="localeEl in availableLocales"      :key="localeEl"      :to="getLocalizedUrl(route.fullPath, localeEl)"      class="locale-link"      :class="{ 'active-locale': localeEl === locale }"      @click="setLocale(localeEl)"    >      {{ getLocaleName(localeEl) }}    </NuxtLink>  </nav></template>

Usar NuxtLink con atributos href adecuados (a través de getLocalizedUrl) asegura que los motores de búsqueda puedan descubrir todas las variantes de idioma de tus páginas. Esto es preferible a cambiar el idioma solo con JavaScript, ya que los rastreadores de motores de búsqueda pueden no seguirlo.

Luego, configura tu app.vue para usar layouts:

<template>  <NuxtLayout>    <NuxtPage />  </NuxtLayout></template>

(Opcional) Paso 6b: Crear un Layout con Navegación

Los layouts de Nuxt te permiten definir una estructura común para tus páginas. Crea un layout por defecto que incluya el selector de idioma y la navegación:

<script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Inicio</Links>    <Links href="/about">Acerca de</Links>  </div></template>

El componente Links (mostrado a continuación) asegura que los enlaces de navegación interna se localicen automáticamente.

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

Nuxt maneja automáticamente el enrutamiento localizado cuando se usa 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 páginas localizadas, simplemente crea tus archivos Vue en el directorio pages/. Aquí tienes dos ejemplos de páginas:

Página de inicio (pages/index.vue):

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("home-page");useHead({  title: content.metaTitle.raw,  meta: [    {      name: "description",      content: content.metaDescription.raw,    },  ],});</script><template>  <h1><content.title /></h1></template>

Página Acerca de (pages/about.vue):

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Usa .raw para acceso a cadena primitiva  meta: [    {      name: "description",      content: content.metaDescription.raw, // Usa .raw para acceder a la cadena primitiva    },  ],});</script><template>  <h1><content.title /></h1></template>

Nota: useHead se importa automáticamente en Nuxt. Puedes acceder a los valores del contenido usando .value (reactivo) o .raw (cadena primitiva) según tus necesidades.

El módulo nuxt-intlayer hará automáticamente:

• Detectar la configuración regional preferida del usuario
• Gestionar el cambio de idioma vía URL
• Establecer el atributo <html lang=""> apropiado
• Manejar 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 la configuración regional actual, puedes crear un componente personalizado Links. Este componente antepone automáticamente a las URLs internas el idioma actual, lo cual es esencial para el SEO y la descubribilidad de las páginas.

<script setup lang="ts">import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";interface Props {  href: string;  locale?: string;}const props = defineProps<Props>();const { locale: currentLocale } = useLocale();// Calcular la ruta finalconst finalPath = computed(() => {  // 1. Verificar si el enlace es externo  const isExternal = /^https?:\/\//.test(props.href || "");  // 2. Si es externo, devolver tal cual (NuxtLink maneja la generación de la etiqueta <a>)  if (isExternal) return props.href;  // 3. Si es interno, localiza la URL  const targetLocale = props.locale || currentLocale.value;  return getLocalizedUrl(props.href, targetLocale);});</script><template>  <NuxtLink :to="finalPath" v-bind="$attrs">    <slot />  </NuxtLink></template>

Luego usa este componente en toda tu aplicación:

<script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Inicio</Links>    <Links href="/about">Acerca de</Links>  </div></template>

Al usar NuxtLink con rutas localizadas, aseguras que:

• Los motores de búsqueda puedan rastrear e indexar todas las versiones de idioma de tus páginas
• Los usuarios puedan compartir URLs localizadas directamente
• El historial del navegador funcione correctamente con URLs que tienen prefijos de locale

(Opcional) Paso 9: Manejar Metadatos y SEO

Nuxt proporciona excelentes capacidades SEO a través del composable useHead (auto-importado). Puedes usar Intlayer para manejar metadatos localizados usando el accesor .raw o .value para obtener el valor primitivo de cadena:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";// useHead se auto-importa en Nuxtconst content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Usa .raw para acceso a cadena primitiva  meta: [    {      name: "description",      content: content.metaDescription.raw, // Usar .raw para acceder al valor primitivo de cadena    },  ],});</script><template>  <h1><content.title /></h1></template>

Alternativamente, puedes usar la función import { getIntlayer } from "intlayer" para obtener el contenido sin reactividad de Vue.

Accediendo a los valores del contenido:

• Usa .raw para obtener el valor primitivo de cadena (no reactivo)
• Usa .value para obtener el valor reactivo
• Usa la sintaxis de componente <content.key /> para soporte del Editor Visual

Crea la declaración de contenido correspondiente:

import { t, type Dictionary } from "intlayer";

const aboutPageContent = {
  key: "about-page",
  content: {
    metaTitle: t({
      en: "About Us - My Company",
      fr: "À Propos - Ma Société",
      es: "Acerca de Nosotros - Mi Empresa",
    }),
    metaDescription: 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",
    }),
    title: t({
      en: "About Us",
      fr: "À Propos",
      es: "Acerca de Nosotros",
    }),
  },
} satisfies Dictionary;

export default aboutPageContent;

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 para 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 ofrece:

• Autocompletado para las claves de traducción.
• Detección de errores en tiempo real para traducciones faltantes.
• Previsualizaciones 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 usando el CMS.