VueCraft NPM

Настройка плагина ​

Опции плагина ​

ts
interface I18nPluginOptions {
  defaultLocale: string
  fallbackLocale?: string
  locales: Record<string, LocaleEntry>
  persistLocale?: boolean
  storageKey?: string
  vueI18nOptions?: Record<string, unknown>
}

defaultLocale ​

string, обязательна. Локаль, загружаемая при старте.

fallbackLocale ​

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

locales ​

Record<string, LocaleEntry>, обязательна. Соответствие кодов локалей объектам сообщений, функциям-загрузчикам или объектам LocaleDefinition. Форматы ниже.

persistLocale ​

boolean · по умолчанию: false. Сохранять выбранную локаль в localStorage и восстанавливать её при следующем визите. См. Сохранение локали ниже.

storageKey ​

string · по умолчанию: 'vue3-i18n-locale'. Ключ, используемый для localStorage, когда persistLocale равен true.

vueI18nOptions ​

object, опционально. Дополнительные опции, передаваемые напрямую в createI18n из vue-i18n.

Форматы записи локали ​

Каждая локаль в карте locales принимает одну из трёх форм. Их можно свободно смешивать в одном конфиге.

1. Простой объект сообщений (синхронный)

ts
locales: {
  en: { buttons: { submit: 'Submit' }, greeting: 'Hello, {name}!' },
}

Сообщения встраиваются в приложение на этапе сборки и доступны сразу.

2. Асинхронная функция-загрузчик (ленивая)

ts
locales: {
  ru: () => import('./locales/ru.json'),
}

JSON-файл загружается только при вызове setLocale('ru'). До этого он никак не влияет на размер начального бандла.

3. LocaleDefinition — сообщения + пользовательские метаданные

ts
locales: {
  en: {
    messages: () => import('./locales/en.json'),
    meta: { display: 'English', flag: '🇬🇧' },
  },
  ru: {
    messages: () => import('./locales/ru.json'),
    meta: { display: 'Русский', flag: '🇷🇺', author: 'Danil Lisin' },
  },
}

meta — произвольный объект, форма которого полностью на усмотрение проекта. Доступен через useLocale().localeMeta и useAvailableLocales().availableLocales[n].meta. Все три формы можно свободно смешивать в одной карте locales.

Сохранение локали ​

Когда установлено persistLocale: true, выбранная локаль сохраняется в localStorage под настроенным storageKey. При следующей загрузке страницы плагин читает это значение и использует его как начальную локаль, откатываясь на defaultLocale, если сохранённое значение не является зарегистрированным кодом локали.

Вызовы localStorage обёрнуты в try/catch, поэтому плагин работает без проблем в окружениях с ограниченным доступом к хранилищу (приватный режим браузера, некоторые контексты iframe).

persistLocale против ручного localStorage ​

  • Настройка — persistLocale: true: одна опция в createVueI18nPlugin. Ручной: читаете при старте, пишете в onLocaleChange.
  • Восстановление при загрузке — persistLocale: true: автоматическое. Ручной: вы читаете ключ и передаёте значение как defaultLocale.
  • Хорошо подходит, когда — persistLocale: true: нужно лишь пережить перезагрузку страницы. Ручной: вы храните дополнительные данные рядом с локалью, используете sessionStorage или делите ключ с другими частями приложения.

Вариант A — доверить это плагину (рекомендуется для большинства проектов):

ts
app.use(createVueI18nPlugin({
  defaultLocale: 'en',
  locales: { ... },
  persistLocale: true,
}))

Вариант B — управлять хранилищем самостоятельно:

ts
const saved = localStorage.getItem('my-locale')
const initial = ['en', 'ru'].includes(saved ?? '') ? saved! : 'en'

app.use(i18nPlugin) // persistLocale НЕ установлен

i18nPlugin.service.onLocaleChange((lang) => {
  localStorage.setItem('my-locale', lang)
})

Не комбинируйте оба варианта для одного и того же ключа хранилища. Если установлен persistLocale: true, а вы также вручную вызываете localStorage.setItem, плагин перезапишет ваше значение при следующем setLocale.