Руководство по локализации i18n в Nuxt

Введение

Современные веб-приложения часто ориентируются на международную аудиторию. Правильно реализованная локализация, также известная как интернационализация (i18n), позволяет адаптировать интерфейс сайта под различные языки, регионы и культурные особенности пользователей. Framework Nuxt, построенный на базе Vue, обладает мощным инструментарием для i18n, позволяя разработчикам легко добавлять поддержку нескольких языков и управлять переводами.

В этой статье подробно разберём, как подключать и настраивать i18n в Nuxt, организовывать структуры файлов для переводов, автоматически определять язык пользователя, обрабатывать динамические переводы в шаблонах и компонентах, обеспечивать SEO для мультиязычных проектов, а также рассмотрим распространённые проблемы и их решения.

Установка и базовая настройка i18n в Nuxt

Подключение nuxt/i18n модуля

Nuxt не имеет встроенной поддержки i18n «из коробки», однако существует официальный модуль [nuxt/i18n], который прост в установке и использовании.

Для начала вам потребуется добавить его в проект:

npm install @nuxtjs/i18n
# или
yarn add @nuxtjs/i18n

Теперь подключите модуль к вашему проекту внутри файла nuxt.config.js:

export default {
  modules: [
    '@nuxtjs/i18n', // добавляем модуль i18n
  ],

  i18n: {
    locales: [
      { code: 'en', iso: 'en-US', file: 'en-US.js', name: 'English' },
      { code: 'ru', iso: 'ru-RU', file: 'ru-RU.js', name: 'Русский' }
    ],
    defaultLocale: 'en',
    lazy: true, // ленивое подключение переводов
    langDir: 'lang/', // папка, где будут храниться файлы переводов
    vueI18n: {
      fallbackLocale: 'en', // язык по умолчанию при отсутствии перевода
    }
  },
}

Коротко о ключевых настройках:

• locales: определяет список поддерживаемых языков и сопоставленные им файлы переводов.
• defaultLocale: язык по умолчанию для вашего приложения.
• lazy и langDir: позволяют подгружать переводы только при необходимости.

Локализация является ключевым фактором для охвата глобальной аудитории, и Nuxt предоставляет отличные инструменты для реализации i18n. Но чтобы создать действительно многоязычный сайт, недостаточно просто перевести текст, необходимо правильно настроить роутинг, хранение локалей и учитывать культурные особенности. Если вы хотите узнать больше о локализации в Nuxt, приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Организация структуры переводов

Лучшей практикой считается хранить переводы в отдельных модулях для каждого языка. Обычно организация файлов выглядит так:

/lang
  en-US.js
  ru-RU.js

Пример файла перевода en-US.js:

export default {
  welcome: 'Welcome to our website!',
  menu: {
    home: 'Home',
    about: 'About Us'
  }
}

И аналогичный ru-RU.js:

export default {
  welcome: 'Добро пожаловать на наш сайт!',
  menu: {
    home: 'Главная',
    about: 'О нас'
  }
}

Это позволяет работать с переводами как с обычными объектами вне зависимости от выбранной локали.

Использование переводов на страницах и в компонентах

Доступ к функциям i18n

В любом компоненте Nuxt вы можете пользоваться $t для получения переводов. Например:

<template>
  <div>
    <h1>{{ $t('welcome') }}</h1>
    <nav>
      <a>{{ $t('menu.home') }}</a>
      <a>{{ $t('menu.about') }}</a>
    </nav>
  </div>
</template>

Функция $t(key) ищет ключ в активном языке и возвращает переведённую строку.

Динамика и параметры в переводах

Часто необходимо вставить переменные в строку перевода. Например, имя пользователя:

В файле перевода:

export default {
  greeting: 'Hello, {name}!'
}

Во Vue компоненте:

<template>
  <p>{{ $t('greeting', { name: userName }) }}</p>
</template>

<script>
export default {
  data() {
    return {
      userName: 'John'
    }
  }
}
</script>

Здесь { name: userName } подставит значение переменной в строку перевода.

Использование v-t для встраивания переводов в разметку

Модуль nuxt/i18n поддерживает директиву v-t для перевода внутри HTML-атрибутов или вложенного текста.

<template>
  <button v-t="'welcome'"></button>
</template>

Это удобно для динамического перевода без необходимости использования методов в JS.

Изменение языка приложения

Программное переключение языка

Для смены языка пользователем вы можете использовать метод $i18n.setLocale(locale). Смотрите, как это реализовано на практике:

<template>
  <div>
    <button @click="switchLang('ru')">Русский</button>
    <button @click="switchLang('en')">English</button>
  </div>
</template>

<script>
export default {
  methods: {
    switchLang(locale) {
      this.$i18n.setLocale(locale)
      // Теперь весь интерфейс будет на выбранном языке
    }
  }
}
</script>

Сохранение выбора пользователя

Для сохранения выбранного языка между сессиями можно использовать cookies или локальное хранилище. Модуль поддерживает этот функционал автоматически через опцию:

i18n: {
  strategy: 'prefix_except_default', // Добавляет язык в URL, кроме языка по умолчанию
  detectBrowserLanguage: {
    useCookie: true,
    cookieKey: 'i18n_redirected',
    alwaysRedirect: true,
    fallbackLocale: 'en'
  }
}

Теперь пользовательский выбор сохраняется, даже если он перезагружает страницу или возвращается позже.

Организация маршрутизации с языковым префиксом

Nuxt/i18n позволяет формировать URL с языковым префиксом, например mysite.com/en/about или mysite.com/ru/about.

Стратегии построения URL

Ключевая опция — strategy:

• 'no_prefix': Без языковых префиксов в URL
• 'prefix': Префикс для каждого языка
• 'prefix_except_default': Префикс добавляется, кроме языка по умолчанию

Пример настройки в nuxt.config.js:

i18n: {
  strategy: 'prefix_except_default',
  // Остальные опции тут ...
}

Автоматическое определение языка пользователя

Эта опция позволяет определить язык пользователя по его браузеру и перенаправить его на нужную языковую версию сайта.

i18n: {
  detectBrowserLanguage: {
    useCookie: true,
    alwaysRedirect: true,
    fallbackLocale: 'en'
  }
}

• detectBrowserLanguage.useCookie: Сохраняет выбор пользователя в cookie
• alwaysRedirect: Перенаправляет пользователя при первом входе
• fallbackLocale: Язык по умолчанию, если автоопределение не удалось

Управление переводом контента

Локализация Meta-тегов и SEO

Важно чтобы title и description страниц были также локализованы, как и контент. Модуль nuxt/i18n предлагает автоматическую интеграцию с meta-информацией.

vueI18n: {
  messages: {
    en: {
      head: {
        title: 'About Us',
        meta: [{ name: 'description', content: 'Learn more about us' }]
      }
    },
    ru: {
      head: {
        title: 'О нас',
        meta: [{ name: 'description', content: 'Узнайте о нас больше' }]
      }
    }
  }
}

В компоненте можно указать:

export default {
  head() {
    return {
      title: this.$t('head.title'),
      meta: this.$t('head.meta')
    }
  }
}

С этим SEO-информация каждой страницы будет корректно соответствовать выбранному языку.

Навигация между языками

Обычно для переключения языка на сайте размещают переключатель языков. Вот пример, как реализовать простой компонент:

<template>
  <div>
    <select v-model="$i18n.locale">
      <option v-for="locale in $i18n.locales" :value="locale.code" :key="locale.code">
        {{ locale.name }}
      </option>
    </select>
  </div>
</template>

При выборе другого значения язык автоматически изменится во всей навигации и контенте.

Лучшие практики организации переводов

Кратко о структуре ключей

Используйте вложенность для группировки — это упростит поиск и редактирование переводов:

export default {
  menu: {
    home: 'Home',
    contact: 'Contact'
  },
  error: {
    notFound: 'Page not found'
  }
}

Синхронизация переводов

Если в проекте много переводов, удобно использовать специальные сервисы или плагины для импорта и экспорта файлов, например, [Phrase] или [Locize]. Это особенно актуально для командной работы.

Проверка полноты переводов

Для поиска отсутствующих ключей используйте [i18n-extract] или подобные утилиты, чтобы не забыть перевести все фрагменты интерфейса.

Работа с асинхронными переводами и SSR

Когда вы используете Nuxt в режиме SSR (Server Side Rendering), важно чтобы переводы были загружены до рендера страницы, иначе возможны моргания интерфейса или проблемы с SEO.

@nuxtjs/i18n при ленивом подключении (lazy: true) автоматически загружает нужный перевод до загрузки страницы. Проблемы возможны, если использовать асинхронные загрузчики или располагать языковые файлы вне папки lang.

Если есть кастомные решения — всегда проверяйте, что нужные переводы появляются вовремя.

Локализация дат, чисел и валют

Nuxt/i18n поддерживает интеграцию с [Intl API], что позволяет форматировать даты, числа и суммы в соответствии с выбранной локалью.

<template>
  <span>{{ $n(1000000, 'currency') }}</span>
</template>

В настройках можно указать шаблоны для форматирования:

vueI18n: {
  numberFormats: {
    en: {
      currency: { style: 'currency', currency: 'USD' }
    },
    ru: {
      currency: { style: 'currency', currency: 'RUB' }
    }
  }
}

Теперь суммы будут отображаться корректно для каждой страны.

Работа с pluralization (множественными числами)

В мультиязычных приложениях необходимо учитывать правила построения фраз для единственного и множественного числа.

Пример для русского:

export default {
  apples: 'У вас {count} яблоко | У вас {count} яблока | У вас {count} яблок'
}

Использование в компоненте:

<p>{{ $tc('apples', count, { count }) }}</p>

• $tc — специальный метод для обработки множественного числа.
• В переводе через | отделяются формы для разных ситуаций (1, 2-4, 5+ в русском).

Валидация форм и собственные сообщения ошибок

Вы можете определять специфические сообщения для ошибок прямо в переводах:

export default {
  error: {
    required: 'Это поле обязательно для заполнения',
    email: 'Введите корректный email'
  }
}

Используйте их во внешних компонентах валидации или в своих обработчиках:

<label>{{ $t('error.required') }}</label>

Особенности Nuxt 3 и переход с Nuxt 2

Если вы начали проект на Nuxt 2, большинство примеров выше будет работать без изменений. В Nuxt 3 поддержка i18n реализована через тот же модуль и особенности настройки схожи, но некоторые детали могут отличаться, например, синтаксис Nuxt config файлов (nuxt.config.ts вместо nuxt.config.js), а также доступ к функциям i18n через Composition API:

import { useI18n } from 'vue-i18n'

export default {
  setup() {
    const { t, locale } = useI18n()
    // Использование t('ключ'), изменение языка через locale.value = ...
  }
}

Заключение

Локализация (i18n) — это не только замена текстов, но и продуманный подход к управлению языковыми и региональными отличиями. Nuxt предоставляет развитый инструментарий через модуль @nuxtjs/i18n, который позволяет удобно интегрировать поддержку разных языков, маршрутизации, SEO, форматов дат и валют. Корректная организация файлов переводов и настройка приложения существенно упрощают масштабирование проекта и улучшают взаимодействие пользователей с вашим приложением независимо от их языка или региона.

Локализация — это важный аспект современных веб-приложений. Чтобы создавать гибкие и масштабируемые приложения, необходимо освоить все возможности фреймворка, включая работу с сервером, базами данных и API. На нашем курсе Nuxt - fullstack Vue фреймворк вы найдете все необходимые знания и навыки для достижения успеха. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как динамически загружать переводы из внешнего API?

Иногда переводы хранятся не в проекте, а на сервере или в стороннем сервисе. Для динамической загрузки можно использовать событие nuxtServerInit или плагин, который перед рендером страницы подтягивает нужные локализации и добавляет их через $i18n.setLocaleMessage(locale, messages).

Как использовать nuxt/i18n вместе с модулем nuxt/content?

Для динамического контента используйте поля lang или i18n в yaml-фронтматтере файлов контента. При рендере страниц отображайте только те записи, что соответствуют текущей $i18n.locale.

Что делать, если на production некоторые переводы не подгружаются?

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

Как тестировать покрытие проекта переводами?

Используйте utility-пакеты для поиска неиспользуемых и отсутствующих ключей: например, [vue-i18n-extract]. Запустите анализ и получите список всех строк, которые требуют внимания.

Можно ли переключать язык по поддомену (например, ru.mysite.com, en.mysite.com)?

Да, в nuxt/i18n предусмотрена опция domain, которая позволяет указывать разные домены для языков. В конфиге пропишите для каждого объекта locale поле domain, после чего Nuxt будет автоматически перенаправлять пользователей.