intlayer: NPM Package to Manage Multilingual Dictionary (i18n)

Intlayer is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, Next.js, and Express.js.

The intlayer package allows you to declare your content anywhere in your code. It converts multilingual content declarations into structured dictionaries that integrate seamlessly into your application. With TypeScript, Intlayer enhances your development by providing stronger, more efficient tools.

Why integrate Intlayer?

• JavaScript-Powered Content Management: Harness the flexibility of JavaScript to define and manage your content efficiently.
• Type-Safe Environment: Utilise TypeScript to ensure all your content definitions are precise and error-free.
• Integrated Content Files: Keep your translations close to their respective components, enhancing maintainability and clarity.

Installation

Install the necessary package using your preferred package manager:

npm install intlayer

Configure Intlayer

Intlayer provides a configuration file to set up your project. Place this file in the root of your project.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

For a complete list of available parameters, refer to the configuration documentation.

Example of use

With Intlayer, you can declare your content in a structured way anywhere in your codebase.

By default, Intlayer scans for files with the extension .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}.

You can modify the default extension by setting the contentDir property in the configuration file.

.├── intlayer.config.ts└── src    ├── ClientComponent    │   ├── index.content.ts    │   └── index.tsx    └── ServerComponent        ├── index.content.ts        └── index.tsx

Declare your content

Here’s an example of content declaration:

import { t, type Dictionary } from "intlayer";const clientComponentContent = {  key: "client-component",  content: {    myTranslatedContent: t({      en: "Hello World",      es: "Hola Mundo",      fr: "Bonjour le monde",    }),    numberOfCar: enu({      "<-1": "Less than minus one car",      "-1": "Minus one car",      "0": "No cars",      "1": "One car",      ">5": "Some cars",      ">19": "Many cars",    }),  },} satisfies Dictionary;export default clientComponentContent;

Build your dictionaries

You can build your dictionaries using the intlayer-cli.

npx intlayer dictionaries build

This command scans all *.content.* files, compiles them, and writes the results to the directory specified in your intlayer.config.ts (by default, ./.intlayer).

A typical output might look like:

.└── .intlayer    ├── dictionary  # Contains the dictionary of your content    │   ├── client-component.json    │   └── server-component.json    ├── main  # Contains the entry point of your dictionary to be used in your application    │   ├── dictionary.cjs    │   └── dictionary.mjs    └── types  # Contains the auto-generated type definitions of your dictionary        ├── intlayer.d.ts  # Contains the auto-generated type definitions of Intlayer        ├── client-component.d.ts        └── server-component.d.ts

Build i18next resources

Intlayer can be configured to build dictionaries for i18next. To do this, you need to add the following configuration to your intlayer.config.ts file:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Instructs Intlayer to generate message files for i18next    dictionaryOutput: ["i18next"],    // The directory where Intlayer will write your message JSON files    i18nextResourcesDir: "./i18next/resources",  },};

For a complete list of available parameters, refer to the configuration documentation.

Output:

.└── i18next    └── resources        ├── en-GB        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

For example, the en-GB/client-component.json might look like:

{  "myTranslatedContent": "Hello World",  "zero_numberOfCar": "No cars",  "one_numberOfCar": "One car",  "two_numberOfCar": "Two cars",  "other_numberOfCar": "Some cars"}

Build next-intl dictionaries

Intlayer can be configured to build dictionaries for i18next or next-intl. For this, you need to add the following configuration to your intlayer.config.ts file:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Tells Intlayer to generate message files for next-intl    dictionaryOutput: ["next-intl"],    // The directory where Intlayer will write your message JSON files    nextIntlMessagesDir: "./i18next/messages",  },};

For a complete list of available parameters, refer to the configuration documentation.

Output:

.└── intl    └── messages        ├── en        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

For example, the en/client-component.json might look like:

{  "myTranslatedContent": "Hello World",  "zero_numberOfCar": "No cars",  "one_numberOfCar": "One car",  "two_numberOfCar": "Two cars",  "other_numberOfCar": "Some cars"}

CLI tools

Intlayer provides a CLI tool to:

• audit your content declarations and complete missing translations
• build dictionaries from your content declarations
• push and pull remote dictionaries from your CMS to your locale project

Consult intlayer-cli for more information.

Use Intlayer in your application

Once your content is declared, you can consume your Intlayer dictionaries in your application.

Intlayer is available as a package for your application.

React Application

To use Intlayer in your React application, you can use react-intlayer.

Next.js Application

To use Intlayer in your Next.js application, you can use next-intlayer.

Express Application

To use Intlayer in your Express application, you can use express-intlayer.

Functions provided by intlayer package

The intlayer package also provides some functions to help you internationalise your application.

• getConfiguration()
• getTranslation()
• getEnumeration()
• getLocaleName()
• getLocaleLang()
• getHTMLTextDir()
• getPathWithoutLocale()
• getMultilingualUrls()
• getLocalizedUrl()
• getPathWithoutLocale()

Doc History

• 5.5.10 - 2025-06-29: Init history