intlayer : Package NPM pour gérer un dictionnaire multilingue (i18n)

Intlayer est une suite de packages conçue spécifiquement pour les développeurs JavaScript. Il est compatible avec des frameworks comme React, Next.js et Express.js.

Le package intlayer vous permet de déclarer votre contenu n'importe où dans votre code. Il convertit les déclarations de contenu multilingue en dictionnaires structurés qui s'intègrent parfaitement dans votre application. Avec TypeScript, Intlayer améliore votre développement en fournissant des outils plus puissants et efficaces.

Pourquoi intégrer Intlayer ?

• Gestion de contenu propulsée par JavaScript : Exploitez la flexibilité de JavaScript pour définir et gérer votre contenu efficacement.
• Environnement typé et sécurisé : Profitez de TypeScript pour garantir que toutes vos définitions de contenu sont précises et sans erreur.
• Fichiers de contenu intégrés : Gardez vos traductions proches de leurs composants respectifs, améliorant ainsi la maintenabilité et la clarté.

Installation

Installez le package nécessaire en utilisant votre gestionnaire de paquets préféré :

npm install intlayer

Configurer Intlayer

Intlayer fournit un fichier de configuration pour configurer votre projet. Placez ce fichier à la racine de votre projet.

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

Pour une liste complète des paramètres disponibles, référez-vous à la documentation de configuration.

Exemple d'utilisation

Avec Intlayer, vous pouvez déclarer votre contenu de manière structurée n'importe où dans votre base de code.

Par défaut, Intlayer recherche les fichiers avec l'extension .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}.

Vous pouvez modifier l'extension par défaut en configurant la propriété contentDir dans le fichier de configuration.

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

Déclarez votre contenu

Voici un exemple de déclaration de contenu :

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": "Beaucoup de voitures",    }),  },} satisfies Dictionary;export default clientComponentContent;

Construisez vos dictionnaires

Vous pouvez construire vos dictionnaires en utilisant le intlayer-cli.

npx intlayer dictionaries build

Cette commande analyse tous les fichiers *.content.*, les compile, et écrit les résultats dans le répertoire spécifié dans votre intlayer.config.ts (par défaut, ./.intlayer).

Une sortie typique pourrait ressembler à :

.└── .intlayer    ├── dictionary  # Contient le dictionnaire de votre contenu    │   ├── client-component.json    │   └── server-component.json    ├── main  # Contient le point d'entrée de votre dictionnaire à utiliser dans votre application    │   ├── dictionary.cjs    │   └── dictionary.mjs    └── types  # Contient les définitions de types auto-générées de votre dictionnaire        ├── intlayer.d.ts  # Contient les définitions de types auto-générées d'Intlayer        ├── client-component.d.ts        └── server-component.d.ts

Construire les ressources i18next

Intlayer peut être configuré pour générer des dictionnaires pour i18next. Pour cela, vous devez ajouter la configuration suivante à votre fichier intlayer.config.ts :

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indique à Intlayer de générer des fichiers de messages pour i18next    dictionaryOutput: ["i18next"],    // Le répertoire où Intlayer écrira vos fichiers JSON de messages    i18nextResourcesDir: "./i18next/resources",  },};

Pour une liste complète des paramètres disponibles, référez-vous à la documentation de configuration.

Sortie :

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

Par exemple, le fichier en/client-component.json pourrait ressembler à :

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

Construire des dictionnaires next-intl

Intlayer peut être configuré pour construire des dictionnaires pour i18next ou next-intl. Pour cela, vous devez ajouter la configuration suivante dans votre fichier intlayer.config.ts :

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indique à Intlayer de générer des fichiers de messages pour i18next    dictionaryOutput: ["next-intl"],    // Le répertoire où Intlayer écrira vos fichiers JSON de messages    nextIntlMessagesDir: "./i18next/messages",  },};

Pour une liste complète des paramètres disponibles, consultez la documentation de configuration.

Sortie :

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

Par exemple, le fichier en/client-component.json pourrait ressembler à :

{  "myTranslatedContent": "Bonjour le monde",  "zero_numberOfCar": "Pas de voiture",  "one_numberOfCar": "Une voiture",  "two_numberOfCar": "Deux voitures",  "other_numberOfCar": "Quelques voitures"}

Outils CLI

Intlayer fournit un outil CLI pour :

• auditer vos déclarations de contenu et compléter les traductions manquantes
• construire des dictionnaires à partir de vos déclarations de contenu
• pousser et récupérer des dictionnaires distants depuis votre CMS vers votre projet local

Consultez intlayer-cli pour plus d'informations.

Utiliser Intlayer dans votre application

Une fois votre contenu déclaré, vous pouvez consommer vos dictionnaires Intlayer dans votre application.

Intlayer est disponible en tant que package pour votre application.

Application React

Pour utiliser Intlayer dans votre application React, vous pouvez utiliser react-intlayer.

Application Next.js

Pour utiliser Intlayer dans votre application Next.js, vous pouvez utiliser next-intlayer.

Application Express

Pour utiliser Intlayer dans votre application Express, vous pouvez utiliser express-intlayer.

Fonctions fournies par le package intlayer

Le package intlayer fournit également certaines fonctions pour vous aider à internationaliser votre application.

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

Historique de la documentation

• 5.5.10 - 2025-06-29 : Historique initial