Справочник по IT

Русский

Українська
English

Русский

Українська
English

Appearance

Модуль @nuxtjs/i18n в Nuxt ​

Модуль @nuxtjs/i18n предоставляет мощные возможности для интернационализации (i18n) вашего Nuxt 3 приложения. Он позволяет легко поддерживать несколько языков, управлять локалями, переводить текст и адаптировать ваше приложение для различных культур.

Установка ​

Для начала установите модуль @nuxtjs/i18n:

bash
npm install --save-dev @nuxtjs/i18n
# или
yarn add -D @nuxtjs/i18n

Затем добавьте @nuxtjs/i18n в секцию modules вашего файла nuxt.config.ts (или nuxt.config.js):

typescript
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
  ],
  i18n: {
    // Настройки модуля (см. ниже)
  },
  // ... другие настройки
});

Настройка (nuxt.config.ts) ​

Модуль @nuxtjs/i18n имеет множество опций конфигурации, которые позволяют настроить его под ваши нужды. Вот некоторые из основных опций:

typescript
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
  ],
  i18n: {
    locales: ['en', 'ru'], // Список поддерживаемых локалей
    defaultLocale: 'en',   // Локаль по умолчанию
    strategy: 'prefix_except_default', // Стратегия определения локали (prefix, prefix_except_default, prefix_and_default, no_prefix)
    detectBrowserLanguage: {
      useCookie: true,
      cookieKey: 'i18n_locale',
      onlyOnRoot: true, // Определять язык браузера только на корневом пути
    },
    vueI18n: {
      legacy: false,
      locale: 'en', // Начальная локаль Vue I18n (должна совпадать с defaultLocale)
      messages: {
        en: {
          welcome: 'Welcome',
          about: 'About Us',
        },
        ru: {
          welcome: 'Добро пожаловать',
          about: 'О нас',
        },
      },
    },
    // lazy: true, // Загружать переводы по требованию (рекомендуется для больших приложений)
    // langDir: '/locales/', // Каталог с файлами локализации (если lazy: true)
    // differentDomains: true, // Использовать разные домены для разных локалей
    // baseUrl: '[https://yourdomain.com](https://yourdomain.com)', // Базовый URL вашего сайта (необходим для differentDomains)
    // ... другие опции
  },
  // ... другие настройки
});

Основные опции:

  • locales: Массив строк, представляющих поддерживаемые языковые коды (например, 'en', 'fr', 'de', 'ru').
  • defaultLocale: Строка, представляющая локаль по умолчанию, которая будет использоваться, если язык пользователя не определен или не поддерживается.
  • strategy: Определяет, как локаль будет отображаться в URL:
    • 'prefix': Добавляет префикс локали ко всем URL (например, /en/about, /ru/about).
    • 'prefix_except_default': Добавляет префикс ко всем локалям, кроме локали по умолчанию (например, /about, /ru/about).
    • 'prefix_and_default': Всегда добавляет префикс локали, включая локаль по умолчанию (например, /en/about, /ru/about, /en/).
    • 'no_prefix': Не добавляет префикс локали к URL. В этом случае вам нужно будет управлять локалью другими способами (например, через домены или параметры запроса).
  • detectBrowserLanguage: Объект, определяющий, следует ли автоматически определять язык пользователя на основе настроек браузера:
    • useCookie: Сохранять выбранную локаль в cookie.
    • cookieKey: Имя cookie, в котором хранится выбранная локаль.
    • onlyOnRoot: Определять язык браузера только на корневом пути (/).
  • vueI18n: Объект конфигурации, который передается непосредственно в vue-i18n. Здесь вы можете определить начальную локаль и сообщения (переводы).
    • legacy: false: Рекомендуется использовать Composition API (vue-i18n@v9).
    • locale: Начальная локаль Vue I18n.
    • messages: Объект, содержащий переводы для каждой локали.
  • lazy: Если установлено в true, переводы будут загружаться по требованию при первом посещении соответствующей локали. Это может улучшить производительность больших приложений.
  • langDir: Путь к каталогу, содержащему файлы локализации (например, /locales/en.json, /locales/ru.json). Используется, если lazy: true.
  • differentDomains: Если установлено в true, вы можете использовать разные домены для разных локалей (например, yourdomain.com для английского и yourdomain.ru для русского).
  • baseUrl: Базовый URL вашего сайта (необходим, если differentDomains: true).

Использование в шаблонах ​

Модуль @nuxtjs/i18n предоставляет компонент <NuxtLink> с расширенной поддержкой локализации и несколько глобальных composables для доступа к функциям i18n.

Используйте <NuxtLink> вместо обычного <a> для навигации между страницами вашего приложения. Он автоматически добавляет правильный префикс локали к URL.

vue
<template>
  <div>
    <NuxtLink to="/">Home</NuxtLink>
    <NuxtLink to="/about">About Us</NuxtLink>
  </div>
</template>

Composables ​

  • useI18n(): Возвращает объект с функциями и свойствами для работы с i18n, включая $t (перевод), locale (текущая локаль), setLocale (изменение локали) и другие.

    vue
    <template>
  <div>
    <h1>{{ $t('welcome') }}</h1>
    <NuxtLink :to="switchLocalePath('about')">{{ $t('about') }}</NuxtLink>
    <select v-model="$i18n.locale">
      <option v-for="locale in availableLocales" :key="locale.code" :value="locale.code">
        {{ locale.name }}
      </option>
    </select>
  </div>
</template>

<script setup>
const { $t, locale } = useI18n();
const { availableLocales } = useI18n();

function switchLocalePath(path) {
  return switchLocalePath(path); // Глобальная функция, предоставляемая модулем
}
</script>

  • switchLocalePath(localeCode): Возвращает путь к текущей странице на указанной локали.

  • localePath(path): Возвращает локализованный путь для указанного пути на текущей локали.

  • localeRoute(route): Возвращает локализованный объект маршрута для указанного объекта маршрута на текущей локали.

  • availableLocales: Реактивное свойство, содержащее массив доступных локалей (включая code и name, если настроено).

  • $i18n.locale: Реактивное свойство, представляющее текущую локаль. Изменение этого значения приведет к переключению языка.

  • $t(key, ...params): Функция для получения перевода по ключу. Может принимать параметры для динамических значений в переводе.

Lazy Loading (загрузка по требованию) ​

Для больших приложений рекомендуется использовать ленивую загрузку переводов (lazy: true). В этом случае вам нужно создать каталог locales/ в корне вашего проекта и поместить туда файлы локализации (например, en.json, ru.json).

Пример структуры каталога locales/:

locales/
├── en.json
└── ru.json

Содержимое en.json:

json
{
  "welcome": "Welcome",
  "about": "About Us",
  "home": "Home"
}

Содержимое ru.json:

json
{
  "welcome": "Добро пожаловать",
  "about": "О нас",
  "home": "Главная"
}

При использовании ленивой загрузки модуль автоматически загрузит соответствующий файл локализации при переключении языка.

Разные домены для разных локалей ​

Если вы хотите использовать разные домены для разных языков (например, yourdomain.com для английского и yourdomain.ru для русского), установите опцию differentDomains в true и определите baseUrl. Затем вам нужно будет настроить опцию domains в конфигурации i18n:

typescript
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
  ],
  i18n: {
    locales: [
      {
        code: 'en',
        domain: 'yourdomain.com',
        iso: 'en-US',
        name: 'English',
      },
      {
        code: 'ru',
        domain: 'yourdomain.ru',
        iso: 'ru-RU',
        name: 'Русский',
      },
    ],
    defaultLocale: 'en',
    strategy: 'prefix_except_default',
    differentDomains: true,
    baseUrl: '[https://yourdomain.com](https://yourdomain.com)',
    vueI18n: {
      legacy: false,
      locale: 'en',
      messages: {
        en: { welcome: 'Welcome' },
        ru: { welcome: 'Добро пожаловать' },
      },
    },
  },
  // ... другие настройки
});

SEO и локализация ​

Модуль @nuxtjs/i18n автоматически добавляет атрибуты hreflang в тег <head> вашего HTML для указания альтернативных языковых версий страниц, что важно для SEO.

Заключение ​

Модуль @nuxtjs/i18n предоставляет мощный и гибкий набор инструментов для интернационализации ваших Nuxt 3 приложений. Благодаря простой настройке, удобным composables и интеграции с маршрутизацией, вы можете легко создавать многоязычные веб-сайты с отличным пользовательским опытом и SEO-оптимизацией.