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) — defaults to the configured defaultLocale.

• 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

Omitting the locale interprets the content with the defaultLocale declared in your configuration.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // Interpreted with the default locale

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

• getIntlayerAsync: Async counterpart loading a single locale chunk.
• getDictionary: Interprets a dictionary object you pass yourself, instead of one looked up by key.
• useIntlayer: The React hook equivalent, reading the locale from the provider.

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