Nouvel Intlayer v9 - Quoi de neuf ?

Bienvenue sur Intlayer v9 ! Cette version majeure marque une étape importante dans la simplification du chemin de migration vers Intlayer avec les packages d'adaptateurs de compatibilité pour les principales bibliothèques i18n (react-i18next, next-intl, vue-i18n, etc.) et ajoute la prise en charge de structures de contenu riches : les Collections et les Variants.

Table des matières

Packages d'adaptateurs de compatibilité

La migration vers Intlayer depuis les bibliothèques i18n populaires est désormais plus facile que jamais. Nous avons créé cinq packages de compatibilité qui exposent les mêmes API publiques exactes que les bibliothèques i18n standard, mais délèguent tout le travail de traduction à Intlayer au moment de l'exécution.

Exposer la même API publique avec un typage strict

En remplaçant les imports, vous bénéficiez de tous les avantages d'Intlayer (y compris la sécurité de type au moment de la compilation par rapport à vos dictionnaires réels) avec des modifications de code minimales :

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

Par exemple, changez simplement :

import { useTranslation } from "react-i18next";

en :

import { useTranslation } from "@intlayer/react-i18next";

Vos clés seront désormais strictement typées par rapport à vos dictionnaires Intlayer, offrant une auto-complétion complète des chemins par points dans votre IDE !

Plugins d'alias de Bundler (Vite, Next.js, Turbopack)

Pour permettre la migration sans réécrire manuellement toutes vos déclarations d'import, chaque package d'adaptateur de compatibilité inclut un plugin de bundler personnalisé (Vite ou Next.js) sous le sous-chemin /plugin.

Ces plugins réécrivent automatiquement les imports existants (par exemple react-i18next ou next-intl) vers leurs équivalents @intlayer/* au moment de la compilation.

Exemple Next.js (Webpack / Turbopack)

Au lieu de withIntlayer, enveloppez votre configuration Next.js avec le plugin de compatibilité :

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Exemple Vite (React, Vue, Solid, Svelte)

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Résolveur d'exécution mutualisé

Tous les adaptateurs de compatibilité acheminent désormais la résolution des traductions via un seul analyseur d'exécution hautement optimisé : @intlayer/core/messageFormat.

• Interpoler le message : Résout les {{var}} standard (espaces et chemins par points), les arguments formatés ICU ({v, number, percent} etc.) et les templates {var} bruts.
• Résolveur de nœuds de message : Résout les nœuds imbriqués : insert(), plural() (règles de pluriel CLDR), enu() (énumération), gender(), les balises HTML, les tableaux et les nœuds de fonction appelables.
• Analyseur de balises tokenisées : Prend en charge les balises XML/HTML en ligne et les balises numérotées (par exemple, <1>children</1>) pour permettre le rendu de texte riche dès la première utilisation.

Spécification des fonctionnalités : Collections & Variants

Intlayer v9 va au-delà des objets clé-valeur statiques, permettant aux dictionnaires de déclarer des structures de mise en page dynamiques entièrement typées de bout en bout.

1. Collections

Définissez une liste d'éléments ordonnés gérée par un CMS (par exemple, FAQ, produits ou listes de blogs) :

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

Utilisation :

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Variants

Proposez des tests A/B, des en-têtes saisonniers, des feature flags ou des pages de destination personnalisées :

Variantes de chaîne (ex. tests A/B)

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ fr: "Bienvenue", en: "Welcome" }),    black_friday: t({ fr: "Acheter maintenant", en: "Shop now" }),  },} satisfies Dictionary;

Utilisation :

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

Variantes d'objet (ex. Dynamic Records)

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ fr: "Code Propre", en: "Clean Code" }),  },} satisfies Dictionary;

Utilisation :

// Récupère uniquement l'élément demandé dynamiquement (nécessite Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

Plugin Vite : Compilateur Bundled & Proxy

Le plugin Vite intlayer() regroupe maintenant le compilateur et le proxy de routage de locale directement, donc la plupart des projets n'ont besoin que d'un seul plugin dans vite.config.ts :

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compilateur : S'active automatiquement lorsque compiler.enabled est défini à true et qu'un chemin compiler.output est configuré. Vous n'avez plus besoin d'enregistrer intlayerCompiler() séparément.
• Proxy : S'active automatiquement en fonction de la nouvelle option routing.enableProxy (true par défaut). Il connecte le middleware de détection de locale / redirection / réécriture en développement, en aperçu et en SSR de production. Vous n'avez plus besoin d'enregistrer intlayerProxy() séparément.

Option routing.enableProxy

Une nouvelle option routing.enableProxy contrôle si le proxy de routage des locales est activé. Par défaut, elle est définie à true. Désactivez-la si vous souhaitez gérer le routage des locales vous-même :

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Par défaut: true  },};export default config;

Les plugins autonomes intlayerCompiler() et intlayerProxy() restent exportés pour les configurations avancées. Les enregistrer aux côtés de intlayer() est sûr — chaque plugin se déduplique et s'exécute une seule fois.

Compilateur désactivé par défaut

Depuis Intlayer v9, le compilateur est désactivé par défaut (compiler.enabled vaut désormais false par défaut). Pour activer l'extraction de vos fichiers .content.ts au moment du build, définissez compiler.enabled: true dans votre configuration :

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Par défaut : false — requis pour activer le compilateur depuis la v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Lorsque le compilateur est désactivé, Intlayer ignore l'étape d'extraction au build et s'appuie sur vos dictionnaires déjà déclarés. Activez-le uniquement lorsque vous souhaitez que le plugin de bundler (@intlayer/swc, @intlayer/babel, ou le plugin Vite intlayer()) extraie le contenu automatiquement.

React Native : imports depuis un seul package

Dans une application React Native ou Expo, vous n'avez plus besoin de jongler entre react-intlayer et react-native-intlayer. Le package react-native-intlayer réexporte désormais l'intégralité de l'API react-intlayer (hooks, utilitaires et les sous-chemins /format, /html, et /markdown), et son IntlayerProvider applique automatiquement les polyfills React Native.

Importez tout depuis le package unique react-native-intlayer :

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

L'importation depuis react-intlayer continue de fonctionner, mais react-native-intlayer est désormais le point d'entrée unique recommandé pour React Native — son provider inclut les polyfills que le provider react-intlayer (orienté web) ne contient pas.

SDK CMS : utilisez Intlayer comme une base de données de contenu headless

Intlayer v9 fournit un SDK clair et auto-authentifié dans @intlayer/api pour interagir avec le CMS de manière programmatique — récupérer des projets, récupérer des dictionnaires, et les pousser ou les mettre à jour depuis votre propre serveur, vos scripts ou votre CI. L'authentification (OAuth2 client_credentials) est gérée et rafraîchie pour vous.

Le SDK est divisé en deux imports distincts afin que votre bundle n'inclue que les domaines que vous utilisez réellement :

1. createIntlayerCMS — un authentificateur léger qui détient les identifiants et le jeton géré (aucun client de domaine n'est inclus).
2. dictionaryEndpoint, projectEndpoint, … — des lieurs d'endpoint par domaine, chacun importé depuis son propre sous-chemin.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// La configuration est optionnelle : les identifiants reviennent à INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET résolus par `@intlayer/config/built`.const cms = createIntlayerCMS();// Lectureconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Écriture — utilisez le CMS comme une base de donnéesawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Sécurité : les identifiants du CMS accordent un accès en écriture à votre contenu. Créez toujours l'authentificateur côté serveur uniquement — n'envoyez jamais clientId / clientSecret au navigateur.

Auto-hébergement

Intlayer v9 offre une prise en charge de première classe pour exécuter votre propre instance Intlayer avec une seule commande — aucun compte Intlayer Cloud requis.

curl -fsSL https://intlayer.org/install.sh | sh

Le programme d'installation télécharge un docker-compose.yml et un .env, génère automatiquement les secrets requis et exécute docker compose up -d. Tout — le tableau de bord, l'API, la base de données, le stockage d'objets et les e-mails transactionnels — s'exécute localement dans des conteneurs.

Services inclus

Chromium (utilisé pour la génération de captures d'écran Puppeteer) est intégré dans l'image du backend — aucun conteneur supplémentaire n'est nécessaire.

Notes de migration depuis la v8

Si vous effectuez une mise à niveau depuis la v8, notez que la v9 n'inclut pas de changements majeurs (breaking changes). Voici cependant les changements clés :

• Compilateur désactivé par défaut : compiler.enabled vaut désormais false par défaut. Si vous dépendez de l'extraction de vos fichiers .content.ts au build, définissez compiler.enabled: true dans votre intlayer.config.ts.
• Plugin Vite : Le compilateur et le proxy de routage de locale sont désormais intégrés dans intlayer(). Si vous avez précédemment enregistré intlayerCompiler() ou intlayerProxy() manuellement, vous pouvez les supprimer — ils sont dédupliqués automatiquement, donc les conserver est sans danger. Utilisez routing.enableProxy: false pour désactiver le proxy.
• Locales et dialectes : Si vous utilisez des dépendances i18n externes, ajoutez leurs plugins d'adaptateur de compatibilité respectifs dans votre configuration ou votre setup de bundler pour réécrire automatiquement les imports.
• Sélecteurs personnalisés : Lors de l'appel de useIntlayer, le deuxième paramètre est désormais réservé à un objet d'options contenant { locale, item, variant }. Si vous passiez auparavant une chaîne de caractères de locale directement, vous pouvez toujours le faire, mais l'utilisation de l'objet d'options est recommandée pour les sélections avancées.
• React Native : react-native-intlayer réexporte désormais l'intégralité de l'API react-intlayer. Dans une application React Native, importez tout depuis react-native-intlayer et supprimez la dépendance directe à react-intlayer. Les imports react-intlayer existants continuent de fonctionner.

Liens utiles

• Guide des packages d'adaptateurs de compatibilité
• Dictionnaires dynamiques - Collections & Variants
• Référence de configuration
• SDK CMS - Accès programmatique avec @intlayer/api
• Guide d'auto-hébergement