Skip to content

aymericzip/intlayer-skills / skills/intlayer-usage

intlayer-usage

Verified

Provides 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.

FileKindSize
LICENCE.mdmarkdown10.7 KB
SKILL.mdskill md3.6 KB
references/concept_how-works-intlayer.mdmarkdown28.7 KB
references/concept_per-locale-file.mdmarkdown7.6 KB
references/get-started.mdmarkdown26.6 KB
references/packages_intlayer_comparePaths.mdmarkdown5.0 KB
references/packages_intlayer_exports.mdmarkdown12.4 KB
references/packages_intlayer_getCanonicalPath.mdmarkdown3.4 KB
references/packages_intlayer_getConfiguration.mdmarkdown4.1 KB
references/packages_intlayer_getDictionary.mdmarkdown4.9 KB
references/packages_intlayer_getDictionaryAsync.mdmarkdown6.3 KB
references/packages_intlayer_getEnumeration.mdmarkdown3.3 KB
references/packages_intlayer_getHTMLTextDir.mdmarkdown2.3 KB
references/packages_intlayer_getIntlayer.mdmarkdown8.7 KB
references/packages_intlayer_getIntlayerAsync.mdmarkdown6.8 KB
references/packages_intlayer_getLocale.mdmarkdown1.1 KB
references/packages_intlayer_getLocaleLang.mdmarkdown1.9 KB
references/packages_intlayer_getLocaleName.mdmarkdown3.5 KB
references/packages_intlayer_getLocalizedPath.mdmarkdown6.8 KB
references/packages_intlayer_getLocalizedUrl.mdmarkdown9.3 KB
references/packages_intlayer_getMultilingualUrls.mdmarkdown8.7 KB
references/packages_intlayer_getPathWithoutLocale.mdmarkdown1.6 KB
references/packages_intlayer_getPrefix.mdmarkdown6.0 KB
references/packages_intlayer_getTranslation.mdmarkdown3.4 KB
references/packages_intlayer_validatePrefix.mdmarkdown1.0 KB
references/packages_react-intlayer_exports.mdmarkdown13.7 KB
references/packages_vite-intlayer_exports.mdmarkdown6.0 KB
references/packages_vite-intlayer_intlayer.mdmarkdown6.0 KB
references/packages_vite-intlayer_intlayerCompiler.mdmarkdown4.2 KB
references/packages_vite-intlayer_intlayerMinify.mdmarkdown3.9 KB
references/packages_vite-intlayer_intlayerProxy.mdmarkdown7.0 KB
references/packages_vite-intlayer_intlayerPrune.mdmarkdown4.7 KB
references/why.mdmarkdown58.2 KB

references/concept_per-locale-file.md

View on GitHub
---
createdAt: 2025-04-18
updatedAt: 2026-09-27
priority: 8
title: "Per-Locale Content Declaration Files"
description: Discover how to declare content per locale in Intlayer. Follow the documentation to understand the different formats and use cases.
keywords:
  - Internationalization
  - Documentation
  - Intlayer
  - Per-Locale
  - TypeScript
  - JavaScript
slugs:
  - doc
  - concept
  - per-locale-file
history:
  - version: 7.3.1
    date: 2025-11-29
    changes: "Add global configuration for per-locale files"
  - version: 5.5.10
    date: 2025-06-29
    changes: "Init history"
author: aymericzip
---

# Declaration of `Per-Locale` Content Declaration in Intlayer

Intlayer supports two ways to declare multilingual content:

- Single file with all translations
- One file per locale (per-locale format)

This flexibility enables:

- Easy migration from other i18n tools
- Support for automated translation workflows
- Clear organization of translations into separate, locale-specific files

## Per-Locale Format

This format is useful when:

- You want to version or override translations independently.
- You're integrating machine or human translation workflows.

You can also split translations into individual locale files by specifying the locale field:

```tsx fileName="hello-world.en.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
import { t, Locales, type Dictionary } from "intlayer";

const helloWorldContent = {
  key: "hello-world",
  locale: Locales.ENGLISH, // Important
  content: { multilingualContent: "Title of my component" },
} satisfies Dictionary;

export default helloWorldContent;
```

```tsx fileName="hello-world.es.content.ts" contentDeclarationFormat={["typescript", "esm"]}
import { t, Locales, type Dictionary } from "intlayer";

const helloWorldContent = {
  key: "hello-world",
  locale: Locales.SPANISH, // Important
  content: { multilingualContent: "Título de mi componente" },
} satisfies Dictionary;

export default helloWorldContent;
```

```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
{
  "$schema": "https://intlayer.org/schema.json",
  "key": "hello-world",
  "locale": "en", // Important
  "content": {
    "multilingualContent": "Title of my component",
  },
}
```

```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
{
  "$schema": "https://intlayer.org/schema.json",
  "key": "hello-world",
  "locale": "es", // Important
  "content": {
    "multilingualContent": "Título de mi componente",
  },
}
```

> Important: Make sure the locale field is defined. It tells Intlayer which language the file represents.

> Note: In both cases, the content declaration file must follow the naming pattern `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` to be recognized by Intlayer. The `.[locale]` suffix is optional and used only as a naming convention.

### Global Configuration for Per-Locale Files

You can configure the global configuration for per-locale files by adding the following to your `intlayer.config.ts` file:

```ts
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  dictionary: {
    locale: Locales.ENGLISH,
  },
};

export default config;
```

Using this configuration, all per-locale files will be generated with the default locale set to English. It also include generation of `.content` files using the `extract` command, and the compiler. (See [Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md) or [Extract](https://github.com/aymericzip/intlayer/edit/main/docs/docs/en/cli/extract.md) for more information.)

- [Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md)

## Single File with Multiple Translations

This format is ideal for:

- Quick iteration in code.
- Seamless integration with the CMS.

This is the recommended approach for most use cases. It centralizes translations, making it easy to iterate and integrate with the CMS.

```tsx fileName="hello-world.content.ts" contentDeclarationFormat={["typescript", "esm"]}
import { t, type Dictionary } from "intlayer";

const helloWorldContent = {
  key: "hello-world",
  content: {
    multilingualContent: t({
      en: "Title of my component",
      es: "Título de mi componente",
    }),
  },
} satisfies Dictionary;

export default helloWorldContent;
```

```js fileName="hello-world.content.cjs" contentDeclarationFormat="json"
const { t } = require("intlayer");

/** @type {import('intlayer').Dictionary} */
const helloWorldContent = {
  key: "hello-world",
  content: {
    multilingualContent: t({
      en: "Title of my component",
      es: "Título de mi componente",
    }),
  },
};

module.exports = helloWorldContent;
```

```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
{
  "$schema": "https://intlayer.org/schema.json",
  "key": "hello-world",
  "content": {
    "multilingualContent": {
      "nodeType": "translation",
      "translation": {
        "en": "Title of my component",
        "es": "Título de mi componente"
      }
    }
  }
}
```

> Recommended: This format is best when using Intlayer's visual editor or managing translations directly in the code.

## Mixing Formats

You can combine both declaration approaches for the same content key. For example:

- Declare your base content statically in a file like index.content.ts.
- Add or override specific translations in separate files such as index.fr.content.ts or index.content.json.

This setup is especially useful when:

- You want to define the initial content structure in code.
- You plan to enrich or complete translations later using the CMS or automated tools.

```bash codeFormat="typescript"
.
└── Components
    └── MyComponent
        ├── index.content.ts
        ├── index.content.json
        └── index.ts
```

### Example

Here a multilingual content declaration file:

```tsx fileName="Components/MyComponent/index.content.ts"
import { t, type Dictionary } from "intlayer";

const helloWorldContent = {
  key: "hello-world",
  locale: Locales.ENGLISH,
  content: {
    multilingualContent: "Title of my component",
    projectName: "My project",
  },
} satisfies Dictionary;

export default helloWorldContent;
```

```json fileName="Components/MyComponent/index.content.json"
{
  "$schema": "https://intlayer.org/schema.json",
  "key": "hello-world",
  "content": {
    "multilingualContent": {
      "nodeType": "translation",
      "translation": {
        "fr": "Titre de mon composant",
        "es": "Título de mi componente"
      }
    }
  }
}
```

Intlayer merges multilingual and per-locale files automatically.

```tsx fileName="Components/MyComponent/index.ts"
import { getIntlayer, Locales } from "intlayer";

const intlayer = getIntlayer("hello-world"); // Default locale is ENGLISH, so it will return the ENGLISH content

console.log(JSON.stringify(intlayer, null, 2));
// Result:
// {
//  "multilingualContent": "Title of my component",
//  "projectName": "My project"
// }

const intlayer = getIntlayer("hello-world", Locales.SPANISH);

console.log(JSON.stringify(intlayer, null, 2));
// Result:
// {
//  "multilingualContent": "Título de mi componente",
//  "projectName": "My project"
// }

const intlayer = getIntlayer("hello-world", Locales.FRENCH);

console.log(JSON.stringify(intlayer, null, 2));
// Result:
// {
//  "multilingualContent": "Titre de mon composant",
//  "projectName": "My project"
// }
```

### Automatic Translation Generation

Use the [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) to auto-fill missing translations based on your preferred services.

- [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md)
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall