---
createdAt: 2026-08-23
updatedAt: 2026-08-23
title: getIntlayer Function Documentation | intlayer
description: See how to use the getIntlayer function for intlayer package
keywords:
  - getIntlayer
  - dictionary
  - content
  - selector
  - Intlayer
  - intlayer
  - Internationalization
  - Documentation
  - JavaScript
  - TypeScript
slugs:
  - doc
  - packages
  - intlayer
  - getIntlayer
history:
  - version: 9.4.0
    date: 2026-08-23
    changes: "Initial documentation"
author: aymericzip
---

# 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

```typescript
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md).
    - `'fr'` — a locale
    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/variants.md) (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

```typescript fileName="src/app.content.ts" codeFormat="typescript"
import { t, type Dictionary } from "intlayer";

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

export default appContent;
```

```typescript codeFormat={["typescript", "esm", "commonjs"]}
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).

```typescript
import { getIntlayer } from "intlayer";

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

### Inside a server handler

```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
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)

```typescript
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) 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`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md) instead.

---

## Related Functions

- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md): Async counterpart loading a single locale chunk.
- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md): Interprets a dictionary object you pass yourself, instead of one looked up by key.
- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useIntlayer.md): The React hook equivalent, reading the locale from the provider.

---

## TypeScript

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