Documentation: getIntlayerAsync Function in intlayer

Description

The getIntlayerAsync function picks one dictionary by its key and resolves its content for a given locale, loading that locale alone.

It is the asynchronous counterpart of getIntlayer, meant for the places a dictionary is read outside of rendering — route head / metadata builders, loaders, server functions.

Where getIntlayer pulls in the merged dictionary holding every locale, the build plugins (@intlayer/babel, @intlayer/swc) rewrite this call into getDictionaryAsync(loaderMap, key, locale), pointing it at the per-locale chunks in .intlayer/dynamic_dictionaries/. The bundle therefore only ever carries the locale actually requested.

Without those plugins — an unoptimized build — the call resolves through the synchronous dictionary registry instead: the same content, without the per-locale split.

Key Features:

• Same typed keys, selectors and returned content as getIntlayer
• Loads only the requested locale chunk in optimized builds
• Concurrent calls for the same chunk share a single load
• Safe to use in async metadata builders, loaders and server functions

Function Signature

getIntlayerAsync(
  key: DictionaryKeys,                        // Required
  localeOrSelector?: LocalesValues | DictionarySelector, // Optional
  plugins?: Plugins[]                         // Optional
): Promise<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.
  • Type: Plugins[]
  • Required: No (Optional)

Returns

• Type: Promise<Content> — a promise resolving to the interpreted content of the dictionary, typed from your declaration.

Example Usage

Basic Usage

import { getIntlayerAsync } from "intlayer";

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

In a TanStack Start route head

Because the locale chunk is loaded on demand, head becomes async:

import { createFileRoute } from "@tanstack/react-router";
import { getIntlayerAsync } from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: async ({ params }) => {
    const { locale } = params;

    const metaContent = await getIntlayerAsync("app", locale);

    return {
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

In a Next.js generateMetadata

import { getIntlayerAsync } from "intlayer";
import type { Metadata } from "next";

export const generateMetadata = async ({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> => {
  const { locale } = await params;
  const { title, description } = await getIntlayerAsync(
    "page-metadata",
    locale
  );

  return { title, description };
};

In a server function

import { createServerFn } from "@tanstack/react-start";
import { getRequestHeader } from "@tanstack/react-start/server";
import { getCookie, getIntlayerAsync, getLocale } from "intlayer";

export const getLocalizedContent = createServerFn().handler(async () => {
  const locale = await getLocale({
    getCookie: (name) => getCookie(name, getRequestHeader("cookie")),
    getHeader: (name) => getRequestHeader(name),
  });

  const content = await getIntlayerAsync("app", locale);

  return { locale, content };
});

getIntlayer vs getIntlayerAsync

Both accept the same arguments and return the same content: switching from one to the other only changes when and how much is loaded.

Related Functions

• getIntlayer: Synchronous equivalent reading the merged dictionary.
• getDictionaryAsync: The lower-level function the build plugins rewrite this call into.
• getLocale: Detects the locale of an incoming request.

TypeScript

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