intlayer

intlayer: 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 to integrate Intlayer?

• JavaScript-Powered Content Management: Harness the flexibility of JavaScript to define and manage your content efficiently.
• Type-Safe Environment: Leverage 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

pnpm add intlayer

yarn add 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 usage

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

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",
      fr: "Bonjour le monde",
      es: "Hola Mundo",
    }),
    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

yarn intlayer build

pnpm intlayer 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  # Contain the dictionary of your content
    │   ├── client-component.json
    │   └── server-component.json
    ├── main  # Contain the entry point of your dictionary to be used in your application
    │   ├── dictionary.cjs
    │   └── dictionary.mjs
    └── types  # Contain the auto-generated type definitions of your dictionary
        ├── intlayer.d.ts  # Contain 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. For that 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 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
        │   ├── 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"
}

Build next-intl dictionaries

Intlayer can be configured to build dictionaries for i18next or next-intl. For that 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 i18next
    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 distant dictionaries from your CMS to your locale project

Consult intlayer-cli for more information.

Use Intlayer into your application

One your content 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 to internationalize your application.

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

Read about Intlayer

• Intlayer Website

• Intlayer Documentation

• Intlayer GitHub

• Ask your questions to our smart documentation