Documentation: getIntlayer Function in intlayer

Description

The getIntlayer function picks one dictionary by its key and returns its content interpreted for a given locale. It is the framework-agnostic counterpart of the useIntlayer hook: same content, same selectors, but usable anywhere a React context is not available, Node scripts, server functions, route loaders, metadata builders, Express/Fastify handlers, tests.

It reads the dictionaries generated by Intlayer in .intlayer/, so the key argument is typed and autocompleted from your own content declarations, and the returned object is fully typed down to each leaf.

Key Features:

• Typed dictionary keys and typed returned content
• Interprets every content node (t(), enu(), cond(), insert(), nest(), md(), html(), file(), gender())
• Accepts a locale or a selector object (collections, variants)
• Results are memoized per key + locale + selector
• Falls back to a safe proxy in development when a dictionary is missing, instead of crashing

Function Signature

getIntlayer(
  key: DictionaryKeys,                        // Required
  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
  plugins?: Plugins[]                         // Optional
): DeepTransformContent<...>

Parameters

• key: DictionaryKeys

  • Description: The key of the dictionary to read, as declared in your content files.
  • Type: DictionaryKeys, a union of every declared dictionary key.
  • Required: Yes

• localeOrSelector: LocalesValues | DictionarySelector

  • Description: The locale to interpret the content with, or a selector object for dynamic dictionaries.
    • 'fr': a locale
    • { item: 2 }: a collection item (omit item to get every item as an array)
    • { variant: 'black-friday' }: a named variant (omit for the default one)
    • { variant: { id: 'prod_abc', userId: '123' } }: a structured variant
    • Any selector can carry a locale: { item: 2, locale: 'fr' }
  • Type: LocalesValues | DictionarySelector
  • Required: No (Optional). When omitted, see Without a locale.

• plugins: Plugins[]

  • Description: Custom node transformers replacing the base interpreter plugins. Advanced use only; omit it to keep the default behaviour.
  • Type: Plugins[]
  • Required: No (Optional)

Returns

• Type: The interpreted content of the dictionary, typed from your declaration.
• Description: A plain object mirroring the content field of your dictionary, where every Intlayer node has been resolved to its final value for the requested locale.

Example Usage

Basic Usage

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

const appContent = {
  key: "app",
  content: {
    title: t({
      en: "Hello",
      fr: "Bonjour",
    }),
  },
} satisfies Dictionary;

export default appContent;

import { getIntlayer } from "intlayer";

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

Without a locale

When no locale is passed, getIntlayer does not jump straight to the default locale. It resolves, in order:

1. The locale of the current request, on the server, when an Intlayer integration handles it: the express-intlayer, fastify-intlayer, hono-intlayer, adonis-intlayer and elysia-intlayer middlewares, the remix-intlayer and astro-intlayer middlewares, and IntlayerProvider / setLocale in React Server Components. Each request is resolved from its own cookies and headers, so concurrent users never share a locale.
2. The locale stored in the browser (cookie, localStorage, sessionStorage), the one a locale switcher persists.
3. The defaultLocale declared in your configuration.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // Request locale, else stored locale, else default locale

The same resolution applies to getDictionary, to the calls the build plugins rewrite, and to useIntlayer / useDictionaryDynamic rendered outside of a provider. Passing a locale explicitly always wins.

getIntlayer is not reactive: after a locale switch, call it again to read the new locale. On a server-rendered page, a call made outside of any provider renders the default locale on the server and the stored locale in the browser, which can cause a hydration mismatch. Mount the provider of your framework, or pass the locale, in that case.

Inside a server handler

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 });
};

With a selector (collections and variants)

import { getIntlayer } from "intlayer";

// A single collection item
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// Every item of the collection, as an ordered array
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// A named variant
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

Behaviour Notes

Caching

Results are memoised in a module-level cache keyed by key + locale + selector. Calling getIntlayer("app", "fr") repeatedly interprets the dictionary once and returns the very same object afterwards.

Missing dictionaries

In development, requesting a key that has no generated dictionary logs a warning once and returns a safe fallback proxy: reading content.title yields the string "app.title" instead of throwing. This keeps a page usable while the missing declaration is fixed. Run the Intlayer build (or the dev server) so the dictionary is generated.

Bundle size

getIntlayer reads the merged dictionary, which holds every locale. In client bundles, the build plugins rewrite the call so only the required content is shipped. When you read content outside of rendering (metadata, loaders, server functions) and want a single locale loaded on demand, use getIntlayerAsync instead.

Related Functions

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>
>;