aymericzip/intlayer-skills / skills/intlayer-usage
intlayer-usage
VerifiedProvides general guidelines for using Intlayer in any project. Use when the user asks to "get started with Intlayer", "declare content files", or understand the "project structure" for internationalization.
references/packages_intlayer_getIntlayer.md
View on GitHub---
createdAt: 2026-08-23
updatedAt: 2026-09-28
priority: 5
title: getIntlayer Function Documentation | intlayer
description: "Use getIntlayer to read a dictionary's content for a locale anywhere, the framework-agnostic counterpart of the useIntlayer hook."
keywords:
- getIntlayer
- dictionary
- content
- selector
- Intlayer
- intlayer
- Internationalization
- Documentation
- JavaScript
- TypeScript
slugs:
- doc
- packages
- intlayer
- getIntlayer
history:
- version: 9.5.12
date: 2026-09-28
changes: "Omitted locale resolves to the request or stored locale before the default locale"
- 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). When omitted, see [Without a locale](#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
```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
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
- [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
```typescript
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) rewrite, and to `useIntlayer` / `useDictionaryDynamic` rendered outside of a provider. Passing a locale explicitly always wins.
- [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)
> `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
```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.
- [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)
- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md)
## Related Functions
- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getIntlayerAsync.md)
- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getDictionary.md)
- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useIntlayer.md)
## 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>
>;
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |