@application-kit/i18n

@application-kit/i18n

Локали, словари и плагин vue-i18n для SSR-приложений на Vue.js и серверный резолв локали запроса. Пакет не знает языков продукта, его словарей и реестра модулей: набор локалей, каркасный словарь и словари модулей приходят параметрами.

Установка

yarn add @application-kit/i18n

Peer-зависимости: vue, vue-i18n — экземпляр у приложения один.

Входы

Импорт любого входа не имеет побочных эффектов и не требует окружения: состояние плагина заводится на установке в приложение, а не на загрузке модуля.

Корень

• defineLocales(locales, fallback) — набор { locales, fallback, isSupported }; тип локали выводится из литерального кортежа, запасная локаль вне списка не компилируется. isSupported(value: unknown) — проверка значения, пришедшего снаружи (cookie, заголовок, профиль).
• LocaleDictionary<L> — половины словаря одного поставщика по локалям; LocaleMessages — одна половина.
• composeMessages(dictionaries, locales) — словарь приложения: каркас первым, модули за ним, поздний перекрывает ранний.
• TranslateFunction — (key, named?) => string, форма t из useI18n(): перевод для кода вне компонентов.
• DictionaryProviderInterface<L> — контракт модуля, несущего свой словарь (getDictionary()).

export const localeSet = defineLocales(['ru', 'en'], 'ru')
export type AppLocale = (typeof localeSet.locales)[number]

Vue.js

app.use(new I18nPlugin({
  localeSet,
  messages: frameworkMessages,
  // Вызывается в контексте приложения: `inject` доступен, реестр модулей приложение достаёт само.
  moduleDictionaries: () => collectModuleDictionaries(inject(MODULE_REGISTRY, undefined)),
}))

• I18nPlugin — ставит vue-i18n (Composition API), стартовая и запасная локаль — localeSet.fallback.
• collectModuleDictionaries(registry) — словари модулей реестра в порядке регистрации. Реестр структурный: достаточно getModules(); словарь берётся у модуля с методом getDictionary.
• setLocale(app, locale), getLocaleReference(app), getTranslate(app) — локаль и перевод конкретного экземпляра приложения для кода вне компонентов. Состояние хранится по App (WeakMap), а не в модуле: на сервере модуль живёт между запросами, и язык одного пользователя не доезжает до другого.
• writeLocaleCookie(locale, { name, maxAgeSeconds? }) — запоминает выбор языка для следующего запроса: Path=/, SameSite=Lax, год по умолчанию, без HttpOnly (cookie пишет браузер, значение не секрет).

Сервер

• resolveLocale(request, { localeSet, cookieName }) — локаль запроса: профиль (request.user.locale) → cookie → Accept-Language с весами q (q=0 отклоняет язык, ru-RU — это ru) → localeSet.fallback. Испорченное значение любого источника читается как «предпочтения нет». Запрос описан структурно (LocaleRequestInterface) — подходит запрос Fastify с @fastify/cookie и без привязки к фреймворку.

Тесты потребителя

• createFakeTranslate(dictionary, defaultLocale) — фабрика (locale = defaultLocale) => TranslateFunction для спек кода, который принимает t зависимостью. Фейк, а не заглушка: ходит в настоящий словарь, подставляет именованные строки и числа ({name}), на отсутствующий ключ бросает TypeError — опечатка в ключе валит спеку, а не проходит как «какой-то текст вернулся».

export const fakeTranslate = createFakeTranslate(messages, localeSet.fallback)

useUserListActions({ translate: fakeTranslate() })