Начало работы с интернационализацией (i18n) с Intlayer и Nuxt

Смотрите Шаблон приложения на GitHub.

Что такое Intlayer?

Intlayer — это инновационная, открытая библиотека для интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.

С помощью Intlayer вы можете:

• Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
• Динамически локализовать метаданные, маршруты и контент.
• Обеспечить поддержку TypeScript с помощью автогенерируемых типов, улучшая автодополнение и обнаружение ошибок.
• Воспользоваться расширенными возможностями, такими как динамическое определение и переключение локали.

Пошаговое руководство по настройке Intlayer в приложении Nuxt

Шаг 1: Установка зависимостей

Установите необходимые пакеты с помощью npm:

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

• intlayer

  Основной пакет, который предоставляет инструменты интернационализации для управления конфигурацией, переводами, объявлением контента, транспиляцией и CLI-командами.

• vue-intlayer Пакет, который интегрирует Intlayer с приложением Vue. Он предоставляет композиционные функции для компонентов Vue.

• nuxt-intlayer Модуль Nuxt, который интегрирует Intlayer с приложениями Nuxt. Он обеспечивает автоматическую настройку, промежуточное ПО для определения локали, управление cookie и перенаправление URL.

Шаг 2: Конфигурация вашего проекта

Создайте файл конфигурации для настройки языков вашего приложения:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Ваши другие локали    ],    defaultLocale: Locales.ENGLISH,  },  content: {    contentDir: ["."], // По умолчанию Intlayer будет отслеживать файлы объявления контента из директории `./src`  },};export default config;

С помощью этого файла конфигурации вы можете настроить локализованные URL, перенаправление через middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

Шаг 3: Интеграция Intlayer в вашу конфигурацию Nuxt

Добавьте модуль intlayer в вашу конфигурацию Nuxt:

import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Ваша существующая конфигурация Nuxt  modules: ["nuxt-intlayer"],});

Модуль nuxt-intlayer автоматически обрабатывает интеграцию Intlayer с Nuxt. Он настраивает построение деклараций контента, отслеживает файлы в режиме разработки, предоставляет middleware для определения локали и управляет локализованной маршрутизацией.

Шаг 4: Объявите ваш контент

Создайте и управляйте вашими декларациями контента для хранения переводов:

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;

Ваши объявления контента могут быть определены в любом месте вашего приложения, при условии, что они включены в каталог contentDir (по умолчанию, ./src). И соответствуют расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Для получения дополнительной информации обратитесь к документации по объявлениям контента.

Шаг 5: Используйте Intlayer в вашем коде

Получайте доступ к вашим словарям контента по всему приложению Nuxt с помощью композиции 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>

Доступ к контенту в Intlayer

Intlayer предлагает различные API для доступа к вашему контенту:

• Синтаксис на основе компонентов (рекомендуется): Используйте синтаксис <myContent /> или <Component :is="myContent" /> для отображения контента как узла Intlayer. Это обеспечивает бесшовную интеграцию с Визуальным редактором и CMS.

• Синтаксис на основе строк: Используйте {{ myContent }} для отображения контента в виде обычного текста, без поддержки Визуального редактора.

• Синтаксис с необработанным HTML: Используйте <div v-html="myContent" /> для отображения контента как необработанного HTML, без поддержки Визуального редактора.

• Синтаксис деструктуризации: Компонент useIntlayer возвращает Proxy с содержимым. Этот прокси можно деструктурировать для доступа к содержимому, сохраняя реактивность.

  • Используйте const content = useIntlayer("myContent"); и {{ content.myContent }} / <content.myContent />.
  • Или используйте const { myContent } = useIntlayer("myContent"); и {{ myContent}} / <myContent/> для деструктуризации содержимого.

(Необязательно) Шаг 6: Изменение языка вашего контента

Для изменения языка вашего контента вы можете использовать функцию setLocale, предоставляемую композаблем useLocale. Эта функция позволяет установить локаль приложения и обновить содержимое соответственно.

Создайте компонент для переключения между языками:

<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";// Получаем информацию о локали и функцию setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Отслеживаем выбранную локаль с помощью refconst selectedLocale = ref(locale.value);// Обновляем локаль при изменении выбораconst changeLocale = () => setLocale(selectedLocale.value);// Синхронизируем selectedLocale с глобальной локальюwatch(  () => 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>

Затем используйте этот компонент на ваших страницах или в макете:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";const content = useIntlayer("app"); // Создайте связанный файл декларации intlayer</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <NuxtPage />    </main>  </div></template>

(Необязательно) Шаг 7: Добавьте локализованную маршрутизацию в ваше приложение

Nuxt автоматически обрабатывает локализованную маршрутизацию при использовании модуля nuxt-intlayer. Это автоматически создает маршруты для каждого языка на основе структуры вашего каталога страниц.

Пример:

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

Чтобы создать локализованную страницу, просто создайте ваши Vue-файлы в каталоге 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>

Модуль nuxt-intlayer автоматически:

• Определяет предпочтительный язык пользователя
• Обрабатывает переключение языка через URL
• Устанавливает соответствующий атрибут <html lang="">
• Управляет куки для языка
• Перенаправляет пользователей на соответствующий локализованный URL

(Необязательно) Шаг 8: Создание компонента локализованной ссылки

Чтобы обеспечить навигацию вашего приложения с учетом текущего языка, вы можете создать пользовательский компонент LocalizedLink. Этот компонент автоматически добавляет префикс текущего языка к внутренним URL.

<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();// Проверяем, является ли ссылка внешнейconst isExternalLink = computed(() => /^https?:\/\//.test(props.to || ""));// Создаем локализованный href для внутренних ссылокconst localizedHref = computed(() =>  isExternalLink.value ? props.to : getLocalizedUrl(props.to, locale.value));</script>

Затем используйте этот компонент по всему вашему приложению:

<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>

(Необязательно) Шаг 9: Обработка метаданных и SEO

Nuxt предоставляет отличные возможности для SEO. Вы можете использовать Intlayer для обработки локализованных метаданных:

<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>

Создайте соответствующее объявление контента:

import { t, type Dictionary } from "intlayer";import type { useSeoMeta } from "nuxt/app";const aboutMetaContent = {  key: "about-meta",  content: {    title: t({      ru: "О нас - Моя компания",      en: "About Us - My Company",      fr: "À Propos - Ma Société",      es: "Acerca de Nosotros - Mi Empresa",    }),    description: t({      ru: "Узнайте больше о нашей компании и нашей миссии",      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;

Настройка TypeScript

Intlayer использует расширение модулей (module augmentation), чтобы использовать преимущества TypeScript и сделать вашу кодовую базу более надежной.

Убедитесь, что ваша конфигурация TypeScript включает автоматически сгенерированные типы.

{  // ... Ваши существующие настройки TypeScript  "include": [    // ... Ваши существующие конфигурации TypeScript    ".intlayer/**/*.ts", // Включить автоматически сгенерированные типы  ],}

Конфигурация Git

Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит избежать их коммита в ваш репозиторий Git.

Для этого вы можете добавить следующие инструкции в файл .gitignore:

# Игнорировать файлы, сгенерированные Intlayer.intlayer

Расширение VS Code

Для улучшения вашего опыта разработки с Intlayer вы можете установить официальное расширение Intlayer для VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автодополнение для ключей переводов.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Встроенный просмотр переведенного контента.
• Быстрые действия для удобного создания и обновления переводов.

Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer для VS Code.

Продвинутые возможности

Для расширения возможностей вы можете реализовать визуальный редактор или вынести ваш контент во внешний CMS.

История документа

• 5.5.10 - 2025-06-29: Инициализация истории