Документация: функция getIntlayer в intlayer

Описание

Функция getIntlayer выбирает один словарь по его ключу и возвращает его содержимое, интерпретированное для заданной локали. Это независимый от фреймворка эквивалент хука useIntlayer: то же содержимое, те же селекторы, но пригодный для использования везде, где React контекст недоступен, скрипты Node, серверные функции, загрузчики маршрутов, построители метаданных, обработчики Express/Fastify, тесты.

Функция читает словари, созданные Intlayer в .intlayer/, поэтому аргумент key типизирован и автодополняется на основе ваших объявлений содержимого, а возвращаемый объект полностью типизирован вплоть до каждого листового узла.

Основные возможности:

• Типизированные ключи словарей и типизированное возвращаемое содержимое
• Интерпретирует каждый узел содержимого (t(), enu(), cond(), insert(), nest(), md(), html(), file(), gender())
• Принимает локаль или объект селектора (коллекции, варианты)
• Результаты кэшируются для каждой комбинации key + locale + selector
• В режиме разработки откатывается на безопасный прокси при отсутствии словаря вместо краша

Сигнатура функции

getIntlayer(
  key: DictionaryKeys,                        // Обязательно
  localeOrSelector?: LocalesValues | DictionarySelector, // Опционально
  plugins?: Plugins[]                         // Опционально
): DeepTransformContent<...>

Параметры

• key: DictionaryKeys

  • Описание: Ключ словаря для чтения, объявленный в ваших файлах контента.
  • Тип: DictionaryKeys, объединение всех объявленных ключей словаря.
  • Обязательно: Да

• localeOrSelector: LocalesValues | DictionarySelector

  • Описание: Локаль для интерпретации контента или объект селектора для динамических словарей.
    • 'fr': локаль
    • { item: 2 }: элемент коллекции (опустите item чтобы получить все элементы как массив)
    • { variant: 'black-friday' }: именованный вариант (опустите для default варианта)
    • { variant: { id: 'prod_abc', userId: '123' } }: структурированный вариант
    • Любой селектор может содержать локаль: { item: 2, locale: 'fr' }
  • Тип: LocalesValues | DictionarySelector
  • Обязательно: Нет (необязательно). Если не указана, см. Без локали.

• plugins: Plugins[]

  • Описание: Пользовательские трансформеры узлов, заменяющие базовые плагины интерпретатора. Только для продвинутого использования; опустите для сохранения поведения по умолчанию.
  • Тип: Plugins[]
  • Обязательно: Нет (необязательно)

Возвращаемое значение

• Тип: Интерпретированное содержимое словаря, типизированное из вашего объявления.
• Описание: Простой объект, отражающий поле content вашего словаря, где каждый узел Intlayer разрешен на его финальное значение для запрошенной локали.

Пример использования

Базовое использование

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: t({
      ru: "Привет",
      en: "Hello",
      fr: "Bonjour",
    }),
  },
} satisfies Dictionary;

export default appContent;

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app", "fr"); // "Bonjour"

Без локали

Если локаль не передана, getIntlayer не переходит сразу к локали по умолчанию. Она определяет локаль в следующем порядке:

1. Локаль текущего запроса, на сервере, когда его обрабатывает интеграция Intlayer: middleware express-intlayer, fastify-intlayer, hono-intlayer, adonis-intlayer и elysia-intlayer, middleware remix-intlayer и astro-intlayer, а также IntlayerProvider / setLocale в React Server Components. Каждый запрос определяется по его собственным cookies и заголовкам, поэтому одновременные пользователи никогда не делят одну локаль.
2. Локаль, сохранённая в браузере (cookie, localStorage, sessionStorage), которую сохраняет переключатель языка.
3. defaultLocale, объявленная в вашей конфигурации.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // Локаль запроса, иначе сохранённая, иначе локаль по умолчанию

То же определение применяется к getDictionary, к вызовам, которые переписывают плагины сборки, и к useIntlayer / useDictionaryDynamic, отрендеренным вне провайдера. Явно переданная локаль всегда имеет приоритет.

getIntlayer не реактивна: после смены локали вызовите её снова, чтобы прочитать новую локаль. На странице с серверным рендерингом вызов вне любого провайдера рендерит локаль по умолчанию на сервере и сохранённую локаль в браузере, что может вызвать hydration mismatch. В этом случае подключите провайдер вашего фреймворка или передайте локаль.

Внутри обработчика сервера

import { getIntlayer, getLocale } from "intlayer";

export const greetingHandler = async (request: Request) => {
  const locale = await getLocale({
    getHeader: (name) => request.headers.get(name) ?? undefined,
  });

  const { title } = getIntlayer("app", locale);

  return Response.json({ title });
};

С селектором (коллекции и варианты)

import { getIntlayer } from "intlayer";

// Один элемент коллекции
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// Все элементы коллекции, как упорядоченный массив
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// Именованный вариант
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

Примечания о поведении

Кеширование

Результаты кешируются на уровне модуля с ключом key + locale + selector. Повторные вызовы getIntlayer("app", "fr") интерпретируют словарь один раз и впоследствии возвращают тот же объект.

Отсутствующие словари

В процессе разработки запрос ключа, для которого не был сгенерирован словарь, регистрирует предупреждение один раз и возвращает безопасный резервный прокси: чтение content.title возвращает строку "app.title" вместо выброса ошибки. Это позволяет странице оставаться функциональной во время исправления недостающей декларации. Запустите сборку Intlayer (или сервер разработки), чтобы словарь был сгенерирован.

Размер бандла

getIntlayer читает объединённый словарь, который содержит все локали. В клиентских бандлах плагины сборки переписывают вызов так, чтобы отправлялось только необходимое содержимое. Когда вы читаете содержимое вне рендеринга (метаданные, загрузчики, серверные функции) и хотите загрузить одну локаль по требованию, используйте getIntlayerAsync.

Связанные функции

TypeScript

function getIntlayer<
  const T extends DictionaryKeys,
  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
>(
  key: T,
  localeOrSelector?: A,
  plugins?: Plugins[]
): DeepTransformContent<
  DictionaryRegistryResult<T, A>,
  IInterpreterPluginState,
  ExtractSelectorLocale<A>
>;