@intlayer/docs 7.0.0-canary.2 → 7.0.0-canary.3

package/docs/fr/releases/v7.md

@@ -0,0 +1,504 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Nouvelle version Intlayer v7 - Quoi de neuf ?
+description: Découvrez les nouveautés d'Intlayer v7. Améliorations majeures des performances, de l'expérience développeur, et nouvelles fonctionnalités pour améliorer votre flux de travail d'internationalisation.
+keywords:
+  - Intlayer
+  - Localisation
+  - Développement
+  - Performance
+  - Expérience Développeur
+  - Fonctionnalités
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 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.
+
+## 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.
+
+```bash
+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 :**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Comportement v7 :**
+
+```tsx
+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 :**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum incluant toutes les locales -> non tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7 :**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Type chaîne -> entièrement tree-shakeable
+
+const 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](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) 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
+
+```typescript
+// intlayer.config.ts
+export 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 :
+
+```typescript
+// Désactiver le stockage
+storage: false
+
+// Types de stockage simples
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie avec attributs personnalisés
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage avec clé personnalisée
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Plusieurs types de stockage pour la redondance
+storage: ['cookie', 'localStorage']
+```
+
+### Exemple de configuration conforme au RGPD
+
+Pour les applications en production qui doivent équilibrer fonctionnalité et conformité au RGPD :
+
+```typescript
+typescript;
+// intlayer.config.ts
+export 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 :
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Peut être surchargé localement pour chaque hook :
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Note :** Les cookies sont activés par défaut.
+**Note :** Consultez les [exigences GDPR concernant les cookies](https://gdpr.eu/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.
+
+---
+
+## 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
+
+```typescript
+// Réécrit le fichier actuel avec toutes les locales
+const content = {
+  key: "example",
+  fill: true, // Réécrit ce fichier
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Remplit un fichier séparé sans modifier le fichier actuel
+const content = {
+  key: "example",
+  fill: "./translations.json", // Crée/actualise translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Désactive l’auto-remplissage
+const content = {
+  key: "example",
+  fill: false, // Pas d’auto-remplissage
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Structure de contenu complexe avec des objets composés
+const 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
+
+```typescript
+// 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`
+
+### Correspondance de migration
+
+#### Correspondance de configuration
+
+| Configuration v6           | Configuration v7                                               |
+| -------------------------- | -------------------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                                    |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                                    |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                           |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                            |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`               |
+| `serverSetCookie: 'never'` | `storage: false` ou supprimer le cookie du tableau de stockage |
+
+#### Exemple de migration
+
+**Avant (v6) :**
+
+````typescript
+export default {
+#### Correspondance de configuration
+
+| Configuration v6           | Configuration v7                                     |
+| -------------------------- | ---------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                          |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                          |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                 |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                  |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     |
+| `serverSetCookie: 'never'` | `storage: false` ou supprimer le cookie du tableau storage |
+
+#### Exemple de migration
+
+**Avant (v6) :**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**Après (v7) :**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // ou 'cookie' si vous avez besoin du stockage par cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Correspondance du contenu du dictionnaire
+
+| Contenu dictionnaire v6 | Contenu dictionnaire v7 |
+| ----------------------- | ----------------------- |
+| `autoFill: xxx`         | `fill: xxx`             |
+
+#### Exemple de migration
+
+**Avant (v6) :**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Réécrit ce fichier
+  content: {
+    title: "Bonjour le monde",
+  },
+};
+```
+
+**Après (v7) :**
+
+```typescript
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/releases/v6.md) pour plus d'informations.
+
+---
+
+## Liens utiles
+
+- [Référence de configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md)
+- [Documentation Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/packages/next-intlayer/index.md)
+- [Types TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Directives RGPD sur les cookies](https://gdpr.eu/cookies/)