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 unoptimised 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 optimised 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"

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