Comenzando a internacionalizar (i18n) con Intlayer, Vite y Vue

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 fácilmente las traducciones utilizando 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 locales.

Guía paso a paso para configurar Intlayer en una aplicación Vite y Vue

Paso 1: Instalar dependencias

Instala los paquetes necesarios usando npm:

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

• 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 la aplicación Vue. Proporciona proveedores de contexto y composables para la internacionalización en Vue.

• vite-intlayer Incluye el plugin de Vite para integrar Intlayer con el empaquetador Vite, así como middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar la 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 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 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 Vite

Agrega el plugin de intlayer en tu configuración.

import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin()],});

El plugin intlayerPlugin() de Vite se utiliza para integrar Intlayer con Vite. Asegura la construcción de archivos de declaración de contenido y los supervisa en modo de desarrollo. Define variables de entorno de Intlayer dentro de la aplicación Vite. Además, proporciona alias para optimizar el rendimiento.

Paso 4: Declara Tu Contenido

Crea y gestiona 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 " }),    officialStarter: t({      en: ", the official Vue + Vite starter",      fr: ", le starter officiel Vue + Vite",      es: ", el starter oficial Vue + Vite",    }),    learnMore: t({      en: "Learn more about IDE Support for Vue in the ",      fr: "En savoir plus sur le support IDE pour Vue dans le ",      es: "Aprenda más sobre el soporte IDE para Vue en el ",    }),    vueDocs: t({      en: "Vue Docs Scaling up Guide",      fr: "Vue Docs Scaling up Guide",      es: "Vue Docs Scaling up Guide",    }),    readTheDocs: t({      en: "Click on the Vite and Vue logos to learn more",      fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",      es: "Haga clic en los logotipos de Vite y Vue 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

Para utilizar las funciones de internacionalización de Intlayer en toda tu aplicación Vue, primero necesitas registrar la instancia singleton de Intlayer en tu archivo principal. Este paso es crucial ya que proporciona el contexto de internacionalización a todos los componentes de tu aplicación, haciendo que las traducciones sean accesibles en cualquier parte de tu árbol de componentes.

import { createApp } from "vue";import { installIntlayer } from "vue-intlayer";import App from "./App.vue";import "./style.css";const app = createApp(App);// Inyectar el proveedor en el nivel superiorinstallIntlayer(app);// Montar la aplicaciónapp.mount("#app");

Accede a tus diccionarios de contenido en toda tu aplicación creando un componente principal de Vue y usando los composables useIntlayer:

<script setup lang="ts">import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const {  count,  edit,  checkOut,  officialStarter,  learnMore,  vueDocs,  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://vuejs.org/guide/quick-start.html#local" target="_blank"      >create-vue</a    >, <officialStarter />  </p>  <p>    <learnMore />    <a      href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"      target="_blank"      ><vueDocs /></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: Use <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>

Luego, usa este componente en tu App.vue:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import HelloWorld from "@components/HelloWorld.vue";import LocaleSwitcher from "@components/LocaleSwitcher.vue";import { ref, watch } from "vue";const content = useIntlayer("app"); // Crear archivo de declaración intlayer relacionado</script><template>  <div>    <LocaleSwitcher />    <a href="https://vite.dev" target="_blank">      <img src="/vite.svg" class="logo" :alt="content.viteLogo" />    </a>    <a href="https://vuejs.org/" target="_blank">      <img src="./assets/vue.svg" class="logo vue" :alt="content.vueLogo" />    </a>  </div>  <HelloWorld :msg="content.title" /></template>

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

Agregar enrutamiento localizado en una aplicación Vue generalmente implica usar Vue Router con prefijos de locales. Esto crea rutas únicas para cada idioma, lo cual es útil para SEO y URLs amigables para SEO.

Ejemplo:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

Primero, instala Vue Router:

npm install intlayer vue-router

Luego, crea una configuración de enrutador que maneje el enrutamiento basado en la localidad:

import {  configuration,  getPathWithoutLocale,  localeFlatMap,  type Locales,} from 'intlayer';import { createIntlayerClient } from 'vue-intlayer';import { createRouter, createWebHistory } from 'vue-router';import HomeView from './views/home/HomeView.vue';import RootView from './views/root/Root.vue';// Obtener la configuración de internacionalizaciónconst { internationalization, middleware } = configuration;const { defaultLocale } = internationalization;/** * Declarar las rutas con rutas específicas por localidad y metadatos. */const routes = localeFlatMap((localizedData) => [  {    path: `${localizedData.urlPrefix}/`,    name: `Root-${localizedData.locale}`,    component: RootView,    meta: {      locale: localizedData.locale,    },  },  {    path: `${localizedData.urlPrefix}/home`,    name: `Home-${localizedData.locale}`,    component: HomeView,    meta: {      locale: localizedData.locale,    },  },]);// Crear la instancia del routerexport const router = createRouter({  history: createWebHistory(),  routes,});// Añadir guardia de navegación para el manejo de localesrouter.beforeEach((to, _from, next) => {  const client = createIntlayerClient();  const metaLocale = to.meta.locale as Locales | undefined;  if (metaLocale) {    // Reutilizar el locale definido en los metadatos de la ruta    client.setLocale(metaLocale);    next();  } else {    // Alternativa: sin locale en los metadatos, posiblemente ruta no coincidente    // Opcional: manejar 404 o redirigir al locale por defecto    client.setLocale(defaultLocale);    if (middleware.prefixDefault) {      next(`/${defaultLocale}${getPathWithoutLocale(to.path)}`);    } else {      next(getPathWithoutLocale(to.path));    }  }});

El nombre se usa para identificar la ruta en el router. Debe ser único entre todas las rutas para evitar conflictos y asegurar una navegación y enlaces adecuados.

Luego, registra el router en tu archivo main.js:

import { createApp } from "vue";import App from "./App.vue";import { router } from "./router";import "./style.css";const app = createApp(App);// Añade el router a la aplicaciónapp.use(router);// Monta la aplicaciónapp.mount("#app");

Luego actualice su archivo App.vue para renderizar el componente RouterView. Este componente mostrará el componente que coincide con la ruta actual.

<script setup lang="ts">import LocaleSwitcher from "@components/LocaleSwitcher.vue";</script><template>  <nav>    <LocaleSwitcher />  </nav>  <RouterView /></template>

Paralelamente, también puede usar el intLayerMiddlewarePlugin para agregar enrutamiento del lado del servidor a su aplicación. Este plugin detectará automáticamente la configuración regional actual basada en la URL y establecerá la cookie de configuración regional correspondiente. Si no se especifica ninguna configuración regional, el plugin determinará la configuración regional más adecuada según las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redirigirá a la configuración regional predeterminada.

import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],});

(Opcional) Paso 8: Cambiar la URL cuando cambia la configuración regional

Para actualizar automáticamente la URL cuando el usuario cambia el idioma, puedes modificar el componente LocaleSwitcher para usar Vue Router:

<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">// Importa ref y watch desde Vueimport { ref, watch } from "vue";// Importa useRouter desde vue-routerimport { useRouter } from "vue-router";// Importa Locales, getLocaleName y getLocalizedUrl desde intlayerimport { Locales, getLocaleName, getLocalizedUrl } from "intlayer";// Importa useLocale desde vue-intlayerimport { useLocale } from "vue-intlayer";// Obtiene Vue Routerconst router = useRouter();// Obtiene la información de la localización y la función setLocaleconst { locale, availableLocales, setLocale } = useLocale({  onLocaleChange: (newLocale) => {    // Obtiene la ruta actual y crea una URL localizada    const currentPath = router.currentRoute.value.fullPath;    const localizedPath = getLocalizedUrl(currentPath, newLocale);    // Navega a la ruta localizada sin recargar la página    router.push(localizedPath);  },});// Rastrea la localización seleccionada con un refconst selectedLocale = ref(locale.value);// Actualizar la configuración regional cuando cambie la selecciónconst changeLocale = () => {  setLocale(selectedLocale.value);};// Mantener selectedLocale sincronizado con la configuración regional globalwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script>

Consejo: Para un mejor SEO y accesibilidad, use etiquetas como <a href="/fr/home" hreflang="fr"> para enlazar a páginas localizadas, como se muestra en el Paso 10. Esto permite que los motores de búsqueda descubran e indexen correctamente las URLs específicas por idioma. Para preservar el comportamiento SPA, puede prevenir la navegación predeterminada con @click.prevent, cambiar la configuración regional usando useLocale y navegar programáticamente usando Vue Router.

<ol class="divide-text/20 divide-y divide-dashed overflow-y-auto p-1">  <li>    <a      hreflang="x-default"      aria-label="Cambiar a inglés"      target="_self"      aria-current="page"      href="/doc/get-started"    >      <div>        <span dir="ltr" lang="en">English</span>        <span>Inglés</span>        <span>EN</span>      </div>    </a>  </li>  <li>    <a      hreflang="es"      aria-label="Cambiar a español"      target="_self"      href="/es/doc/get-started"    >      <div>        <span dir="ltr" lang="es">Español</span>        <span>Español</span>        <span>ES</span>      </div>    </a>  </li></ol>

(Opcional) Paso 9: Cambiar los atributos de idioma y dirección en HTML

Cuando tu aplicación soporta múltiples idiomas, es crucial actualizar los atributos lang y dir de la etiqueta <html> para que coincidan con la configuración regional actual. Hacer esto garantiza:

• Accesibilidad: Los lectores de pantalla y las tecnologías de asistencia dependen del atributo lang correcto para pronunciar e interpretar el contenido con precisión.
• Renderizado de texto: El atributo dir (dirección) asegura que el texto se muestre en el orden adecuado (por ejemplo, de izquierda a derecha para inglés, de derecha a izquierda para árabe o hebreo), lo cual es esencial para la legibilidad.
• SEO: Los motores de búsqueda utilizan el atributo lang para determinar el idioma de tu página, ayudando a mostrar el contenido localizado correcto en los resultados de búsqueda.

Al actualizar estos atributos dinámicamente cuando cambia la configuración regional, garantizas una experiencia coherente y accesible para los usuarios en todos los idiomas soportados.

import { watch } from "vue";import { useLocale } from "vue-intlayer";import { getHTMLTextDir } from "intlayer";/** * Composable que actualiza los atributos `lang` y `dir` del elemento HTML <html> * basándose en la configuración regional actual. * * @example * // En tu App.vue o un componente global * import { useI18nHTMLAttributes } from './composables/useI18nHTMLAttributes' * * useI18nHTMLAttributes() */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  // Actualiza los atributos HTML cada vez que cambia la configuración regional  watch(    () => locale.value,    (newLocale) => {      if (!newLocale) return;      // Actualiza el atributo de idioma      document.documentElement.lang = newLocale;      // Establece la dirección del texto (ltr para la mayoría de idiomas, rtl para árabe, hebreo, etc.)      document.documentElement.dir = getHTMLTextDir(newLocale);    },    { immediate: true }  );};

Usa este composable en tu App.vue o en un componente global:

<script setup lang="ts">import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";// Aplica los atributos HTML basados en la configuración regional actualuseI18nHTMLAttributes();</script><template>  <!-- La plantilla de tu aplicación --></template>

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

Para garantizar que la navegación de su aplicación respete la configuración regional actual, puede crear un componente personalizado Link. Este componente antepone automáticamente a las URL internas el idioma actual. Por ejemplo, cuando un usuario francófono hace clic en un enlace a la página "Acerca de", es redirigido a /fr/about en lugar de /about.

Este comportamiento es útil por varias razones:

• SEO y experiencia del usuario: Las URL localizadas ayudan a los motores de búsqueda a indexar correctamente las páginas específicas de cada idioma y proporcionan a los usuarios contenido en su idioma preferido.
• Consistencia: Al usar un enlace localizado en toda su aplicación, garantiza que la navegación se mantenga dentro de la configuración regional actual, evitando cambios inesperados de idioma. /// Mantenibilidad: Centralizar la lógica de localización en un solo componente simplifica la gestión de URLs, haciendo que tu base de código sea más fácil de mantener y ampliar a medida que tu aplicación crece.

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

Para usar con Vue Router, crea una versión específica para el router:

<template>  <router-link :to="localizedTo" v-bind="$attrs">    <slot />  </router-link></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: [String, Object],    required: true,  },});const { locale } = useLocale();// Crear la propiedad 'to' localizada para router-linkconst localizedTo = computed(() => {  if (typeof props.to === "string") {    return getLocalizedUrl(props.to, locale.value);  } else {    // Si 'to' es un objeto, localiza la propiedad path    return {      ...props.to,      path: getLocalizedUrl(props.to.path ?? "/", locale.value),    };  }});</script>

Usa estos componentes en tu aplicación:

<template>  <div>    <!-- Vue router  -->    <RouterLink to="/">Raíz</RouterLink>    <RouterLink to="/home">Inicio</RouterLink>    <!-- Otros -->    <Link href="/">Raíz</Link>    <Link href="/home">Inicio</Link>  </div></template><script setup lang="ts">import Link from "@components/Link.vue";import RouterLink from "@components/RouterLink.vue";</script>

(Opcional) Paso 11: Renderizar Markdown

Intlayer soporta la renderización de contenido Markdown directamente en tu aplicación Vue. Por defecto, Markdown se trata como texto plano. Para convertir Markdown en HTML enriquecido, puedes integrar markdown-it, un parser de Markdown.

Esto es particularmente útil cuando tus traducciones incluyen contenido formateado como listas, enlaces o énfasis.

Por defecto, Intlayer renderiza markdown como cadena. Pero Intlayer también proporciona una forma de renderizar markdown en HTML usando la función installIntlayerMarkdown.

Para ver cómo declarar contenido markdown usando el paquete intlayer, consulta la documentación de markdown.

import MarkdownIt from "markdown-it";import { createApp, h } from "vue";import { installIntlayer, installIntlayerMarkdown } from "vue-intlayer";const app = createApp(App);installIntlayer(app);const md = new MarkdownIt({  html: true, // permitir etiquetas HTML  linkify: true, // auto-enlazar URLs  typographer: true, // habilitar comillas inteligentes, guiones, etc.});// Indicar a Intlayer que use md.render() cada vez que necesite convertir markdown en HTMLinstallIntlayerMarkdown(app, (markdown) => {  const html = md.render(markdown);  return h("div", { innerHTML: html });});

Una vez registrado, puedes usar la sintaxis basada en componentes para mostrar el contenido Markdown directamente:

<template>  <div>    <myMarkdownContent />  </div></template><script setup lang="ts">import { useIntlayer } from "vue-intlayer";const { myMarkdownContent } = useIntlayer("my-component");</script>

Configurar TypeScript

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

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

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

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.
• Previsualizaciones en línea del contenido traducido.
• Acciones rápidas para crear y actualizar traducciones fácilmente.

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

Para hacer esto, 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, 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.

Historial del Documento

• 5.5.10 - 2025-06-29: Historial inicial