Nouvelle version Intlayer v7 - Quoi de neuf ?

Bienvenue dans Intlayer v7 ! Cette version majeure introduit des améliorations significatives en termes de performance, de sécurité des types et d'expérience développeur. Voici les points forts, avec des notes de migration et des exemples pratiques.

Table of contents

Points forts

• Stratégie de mise en cache pour des builds plus rapides
• Génération améliorée des types TypeScript avec des types spécifiques à chaque locale
• Optimisation du bundle : Locales sous forme de chaînes de caractères au lieu d'énumérations
• Nouveaux modes de routage : prefix-no-default, prefix-all, no-prefix, search-params
• Stockage des locales conforme au RGPD avec localStorage par défaut
• Configuration flexible du stockage : cookies, localStorage, sessionStorage, ou plusieurs à la fois
• Taille du package Visual Editor réduite de 30 %
• Options de configuration du middleware améliorées
• Comportement mis à jour de la commande fill pour une meilleure gestion du contenu
• Stabilité renforcée avec des mises à jour complètes des fichiers de déclaration de contenu
• Gestion intelligente des tentatives de nouvelle traduction pour une meilleure précision
• Parallélisation pour un traitement plus rapide des traductions
• Découpage intelligent pour gérer les gros fichiers dans les limites du contexte IA

Performance : Mise en cache pour des builds plus rapides

Au lieu de reconstruire les déclarations de contenu avec esbuild à chaque build, la version 7 met en œuvre une stratégie de mise en cache qui accélère le processus de build.

npx intlayer build

Le nouveau système de mise en cache :

• Stocke les déclarations de contenu compilées pour éviter un traitement redondant
• Détecte les modifications et reconstruit uniquement les fichiers modifiés
• Réduit significativement les temps de build pour les grands projets

TypeScript : génération de types spécifiques à chaque locale

Les types TypeScript sont désormais générés par locale, offrant un typage plus strict et éliminant les types union à travers toutes les locales.

Comportement v6 :

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Comportement v7 :

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "Mon titre" }

Avantages :

• Autocomplétion plus précise dans votre IDE
• Meilleure sécurité des types sans pollution de type entre locales
• Performance améliorée grâce à la réduction de la complexité des types

Optimisation du bundle : Locales en tant que chaînes de caractères

Le type Locales n'est plus un enum, ce qui signifie qu'il est désormais entièrement tree-shakeable et ne gonflera plus votre bundle avec des milliers d'enregistrements de locales inutilisées.

v6 :

import { Locales } from "intlayer";// Enum incluant toutes les locales -> non tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7 :

import { Locales, Locale } from "intlayer";// Type chaîne -> entièrement tree-shakeableconst locale: Locale = Locales.ENGLISH;

Parce que Locales n'est plus un enum, vous devrez changer le type de Locales à Locale pour obtenir la locale en tant que type.

Voir les détails de l'implémentation pour plus d'informations.

Nouveaux modes de routage pour plus de flexibilité

La version 7 introduit une configuration unifiée routing.mode qui remplace les options précédentes prefixDefault et noPrefix, offrant un contrôle plus granulaire sur la structure des URL.

Modes de routage disponibles

• prefix-no-default (par défaut) : La locale par défaut n'a pas de préfixe, les autres locales en ont un
  • /dashboard (en) ou /fr/dashboard (fr)
• prefix-all : Toutes les locales ont un préfixe
  • /en/dashboard (en) ou /fr/dashboard (fr)
• no-prefix : Pas de préfixes de locale dans les URLs (locale gérée via le stockage/les en-têtes)
  • /dashboard pour toutes les locales
• search-params : Locale passée en paramètre de requête
  • /dashboard?locale=en ou /dashboard?locale=fr

Configuration de base

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // par défaut  },};

Conformité RGPD : stockage localStorage / cookies

La version 7 privilégie la confidentialité des utilisateurs en utilisant localStorage comme mécanisme de stockage par défaut au lieu des cookies. Ce changement facilite la conformité au RGPD en évitant les exigences de consentement aux cookies pour les préférences de locale.

Options de configuration du stockage

Le nouveau champ routing.storage est également disponible en plus des options précédentes middleware.cookieName et middleware.serverSetCookie, offrant des configurations de stockage flexibles :

// Désactiver le stockagestorage: false// Types de stockage simplesstorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie avec attributs personnalisésstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage avec clé personnaliséestorage: {  type: 'localStorage',  name: 'custom-locale'}// Plusieurs types de stockage pour la redondancestorage: ['cookie', 'localStorage']

Exemple de configuration conforme au RGPD

Pour les applications en production qui doivent équilibrer fonctionnalité et conformité au RGPD :

typescript;// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Stockage principal (pas de consentement nécessaire)        name: "user-locale",      },      {        type: "cookie", // Stockage optionnel par cookie (consentement requis)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Activer / désactiver le stockage par cookie

Exemple avec React / Next.js :

Peut être défini globalement :

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Peut être surchargé localement pour chaque hook :

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Note : Les cookies sont activés par défaut. Note : Consultez les exigences GDPR concernant les cookies pour votre cas d'utilisation spécifique.

Éditeur Visuel : paquet 30 % plus léger

Le paquet de l'Éditeur Visuel a été optimisé pour être 30 % plus léger que la version précédente, grâce à :

• Améliorations des performances de l'éditeur de code
• Suppression des dépendances inutiles aux paquets principaux d'Intlayer
• Meilleur tree-shaking et empaquetage des modules

Cela se traduit par des temps de téléchargement plus rapides et une meilleure performance à l'exécution pour votre application.

Formatage automatique du code : configuration de formatCommand

v7 introduit l'option formatCommand dans la configuration de l'éditeur, vous permettant de formater automatiquement les fichiers de contenu lorsqu'ils sont écrits par Intlayer. Cela garantit un style de code et un formatage cohérents dans vos fichiers de déclaration de contenu.

S'il n'est pas défini, Intlayer essaiera de détecter automatiquement la commande de formatage. En essayant de résoudre les commandes suivantes : prettier, biome, eslint.

Configuration

L'option formatCommand accepte un modèle de chaîne où {{file}} sera remplacé par le chemin de fichier réel :

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Formatters supportés

Vous pouvez utiliser n'importe quel formateur de code qui accepte les chemins de fichiers comme arguments :

Utilisation de Biome :

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Utilisation de Prettier :

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Utilisation d'ESLint :

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Utilisation du formateur intégré de Bun :

formatCommand: 'bun format "{{file}}"';

Avantages

• Formatage cohérent : Tous les fichiers de contenu sont automatiquement formatés selon les directives de style de votre projet
• Expérience développeur : Pas besoin de formater manuellement les fichiers après qu'Intlayer les ait écrits
• Cohérence d'équipe : Assure que tous les membres de l'équipe ont le même formatage appliqué aux fichiers de contenu
• Intégration CI/CD : Les fichiers de contenu maintiennent un formatage cohérent dans les workflows automatisés

Fonctionnement

Lorsqu'Intlayer écrit ou met à jour un fichier de déclaration de contenu (.content.ts, .content.js, etc.), il exécute automatiquement la commande de format spécifiée sur le fichier. L'espace réservé {{file}} est remplacé par le chemin d'accès réel du fichier, et la commande est exécutée dans le répertoire de base du projet.

Configuration du dictionnaire : Meilleure organisation et structure

v7 introduit une nouvelle section de configuration dictionary dédiée qui offre une meilleure organisation des paramètres liés au dictionnaire et une gestion de contenu améliorée.

Nouvelle structure de configuration du dictionnaire

La propriété fill a été déplacée de la section content vers une nouvelle section dictionary, offrant une séparation des responsabilités plus claire :

Configuration v6 :

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

Configuration v7 :

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Avantages de la nouvelle structure

• Organisation plus claire : Les paramètres spécifiques au dictionnaire sont maintenant regroupés
• Meilleure séparation des préoccupations : La découverte de contenu et les opérations de dictionnaire sont clairement séparées
• Maintenabilité améliorée : Plus facile à comprendre et à modifier les configurations liées au dictionnaire
• Extensibilité future : La section dictionnaire peut accueillir des paramètres supplémentaires spécifiques au dictionnaire
• Gestion complète du dictionnaire : Inclut des propriétés comme title, live, priority, tags, version, et description pour créer et gérer de nouveaux dictionnaires

Utilisation de la configuration

La configuration du dictionnaire sert deux objectifs principaux :

1. Valeurs par défaut : Définir les valeurs par défaut lors de la création de fichiers de déclaration de contenu
2. Comportement de secours : Fournir des valeurs de secours lorsque des champs spécifiques ne sont pas définis, vous permettant de définir le comportement du dictionnaire globalement

La section dictionnaire inclut des propriétés complètes pour la gestion du dictionnaire :

• fill : Comportement de remplissage automatique pour la génération de contenu
• title : Titre par défaut pour les nouveaux dictionnaires
• live : Configuration de synchronisation en direct pour les mises à jour en temps réel
• priority : Paramètres de priorité pour la résolution du dictionnaire
• tags : Tags par défaut pour l'organisation du contenu
• version : Gestion des versions pour les mises à jour du dictionnaire
• description : Description par défaut pour le nouveau contenu

Pour plus d'informations sur les fichiers de déclaration de contenu et la façon dont les valeurs de configuration sont appliquées, consultez la Documentation du fichier de contenu.

Commande fill : comportement mis à jour pour une meilleure gestion du contenu

La version 7 introduit un comportement amélioré pour la commande fill, offrant une gestion du contenu plus prévisible et flexible :

Nouveau comportement de fill

• fill: true - Réécrit le fichier actuel avec le contenu rempli pour toutes les locales
• fill: "path/to/file" - Remplit le fichier spécifié sans modifier le fichier actuel
• fill: false - Désactive complètement le remplissage automatique

Support amélioré pour les structures de contenu complexes

La commande fill prend désormais en charge des structures de déclaration de contenu complexes, incluant :

• Objets composés : Déclarations de contenu qui référencent d'autres objets
• Contenu déstructuré : Contenu utilisant des motifs de déstructuration
• Références imbriquées : Objets qui s'appellent mutuellement dans des hiérarchies complexes
• Structures de contenu dynamiques : Contenu avec des propriétés conditionnelles ou calculées

Avantages

• Intention plus claire : Le comportement est désormais plus explicite sur ce qui est modifié
• Meilleure séparation : Les fichiers de contenu peuvent être conservés séparément des traductions remplies
• Flux de travail amélioré : Les développeurs ont plus de contrôle sur l’endroit où les traductions sont stockées
• Support des structures complexes : Gérer des architectures de contenu sophistiquées avec plusieurs objets interconnectés

Exemple d’utilisation

// Réécrit le fichier actuel avec toutes les localesconst content = {  key: "example",  fill: true, // Réécrit ce fichier  content: {    title: "Hello World",  },};// Remplit un fichier séparé sans modifier le fichier actuelconst content = {  key: "example",  fill: "./translations.json", // Crée/actualise translations.json  content: {    title: "Hello World",  },};// Désactive l’auto-remplissageconst content = {  key: "example",  fill: false, // Pas d’auto-remplissage  content: {    title: "Hello World",  },};// Structure de contenu complexe avec des objets composésconst sharedContent = {  buttons: {    save: "Enregistrer",    cancel: "Annuler",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Références à d'autres objets    sharedContent,    // Contenu déstructuré    ...sharedContent,    // Références imbriquées    sections: [      {        ...sharedContent.buttons,        header: "Section 1",      },    ],  },};

Stabilité améliorée et gestion des traductions

La version 7 introduit plusieurs améliorations pour rendre la traduction de contenu plus fiable et efficace :

Mises à jour complètes des fichiers de déclaration de contenu

Le système met désormais à jour les fichiers .content.{ts,js,cjs,mjs} plutôt que de faire des mises à jour partielles, garantissant :

• Intégrité des données : La réécriture complète des fichiers empêche les mises à jour partielles qui pourraient corrompre le contenu
• Cohérence : Toutes les locales sont mises à jour de manière atomique, maintenant la synchronisation
• Fiabilité : Réduit le risque de fichiers de contenu incomplets ou mal formés

Gestion intelligente des nouvelles tentatives

De nouveaux mécanismes de retry empêchent la transmission de contenu dans des formats incorrects, et évitent de casser tout le processus de remplissage si une requête échoue.

Parallélisation pour un traitement plus rapide

Les opérations de traduction s'exécutent désormais dans une file d'attente pour être traitées en parallèle. Cela accélère considérablement le processus.

Découpage intelligent pour les gros fichiers

Des stratégies avancées de découpage gèrent les gros fichiers de contenu sans dépasser les limites de contexte de l'IA :

Exemple de flux de travail

// Le gros fichier de contenu est automatiquement découpéconst content = {  key: "large-documentation",  fill: true,  content: {    // Contenu volumineux automatiquement découpé pour le traitement par IA    introduction: "..." // plus de 5000 caractères    sections: [      // Plusieurs grandes sections    ]  }};

Le système effectue automatiquement :

1. Analyse la taille et la structure du contenu
2. Découpe le contenu de manière appropriée
3. Traite les morceaux en parallèle
4. Valide et réessaie si nécessaire
5. Reconstruit le fichier complet

Notes de migration depuis la v6

Configurations supprimées

• middleware.cookieName : Remplacé par routing.storage
• middleware.serverSetCookie : Remplacé par routing.storage
• middleware.prefixDefault : Remplacé par routing.mode
• middleware.noPrefix : Remplacé par routing.mode

Nouvelles configurations

• editor.formatCommand: Nouvelle option pour le formatage automatique du code des fichiers de contenu

Correspondance de migration

Correspondance de configuration

Exemple de migration

Avant (v6) :

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Après (v7) :

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // ou 'cookie' si vous avez besoin du stockage par cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Correspondance du contenu du dictionnaire

Exemple de migration

Avant (v6) :

const content = {  key: "example",  autoFill: true, // Réécrit ce fichier  content: {    title: "Bonjour le monde",  },};

Après (v7) :

const content = {  key: "example",  fill: true, // Réécrit ce fichier  content: {    title: "Bonjour le monde",  },};

Notes de migration de la v5 à la v6

Consultez les notes de migration de la v5 à la v6 pour plus d'informations.

Liens utiles

• Référence de configuration
• Documentation Middleware
• Types TypeScript
• Directives RGPD sur les cookies