@intlayer/docs 8.12.1 → 8.12.3

package/docs/fr/migration_from_vue-i18n_to_intlayer.md

@@ -0,0 +1,342 @@
+---
+createdAt: 2026-06-05
+updatedAt: 2026-06-05
+title: "Migrer de vue-i18n à Intlayer | Internationalisation (i18n)"
+description: "Découvrez comment migrer votre application Vue ou Nuxt de vue-i18n à Intlayer — étape par étape, sans casser votre code existant. Utilisez l'adaptateur de compatibilité @intlayer/vue-i18n pour une transition en douceur."
+keywords:
+  - vue-i18n
+  - intlayer
+  - migration
+  - internationalisation
+  - i18n
+  - Nuxt
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - migration
+  - vue-i18n
+history:
+  - version: 8.13.0
+    date: 2026-06-05
+    changes: "Init history"
+---
+
+# Migrer de vue-i18n à Intlayer
+
+## Pourquoi migrer de vue-i18n à Intlayer ?
+
+<AccordionGroup>
+
+<Accordion header="Taille du bundle">
+
+Au lieu de charger des fichiers JSON massifs dans vos pages, ne chargez que le contenu nécessaire. Intlayer aide à **réduire la taille de votre bundle et de vos pages jusqu'à 50 %**.
+
+</Accordion>
+
+<Accordion header="Maintenabilité">
+
+Scoper le contenu de votre application **facilite la maintenance** pour les applications à grande échelle. Vous pouvez dupliquer ou supprimer un dossier de fonctionnalité entier sans avoir la charge mentale de revoir toute votre base de code de contenu. De plus, Intlayer est **entièrement typé** pour garantir l'exactitude de votre contenu.
+
+Intlayer est également la solution avec le **développement le plus actif** dans l'écosystème i18n — les problèmes sont résolus rapidement, de nouveaux adaptateurs de framework arrivent régulièrement, et l'API principale est continuellement affinée en fonction des retours de production réels.
+
+</Accordion>
+
+<Accordion header="Agent IA">
+
+Colocaliser le contenu **réduit le contexte nécessaire** pour les Grands Modèles de Langage (LLM). Intlayer est également livré avec une suite d'outils, tels qu'une **CLI** pour tester les traductions manquantes, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/mcp_server.md)**, et des **[compétences d'agent](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/agent_skills.md)**, pour rendre l'expérience développeur (DX) encore plus fluide pour les agents IA.
+
+</Accordion>
+
+<Accordion header="Automatisation">
+
+Utilisez l'automatisation pour traduire dans votre pipeline CI/CD en utilisant le LLM de votre choix au coût de votre fournisseur d'IA. Intlayer propose également un **compilateur** pour automatiser l'extraction de contenu, ainsi qu'une [plateforme web](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md) pour aider à **traduire en arrière-plan**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecter des fichiers JSON massifs aux composants peut entraîner des problèmes de performance et de réactivité. Intlayer optimise le chargement de votre contenu au moment de la construction.
+
+</Accordion>
+
+<Accordion header="Évolutivité avec des non-développeurs">
+
+Plus qu'une simple solution i18n, Intlayer fournit un **[éditeur visuel](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_visual_editor.md)** auto-hébergé et un **[CMS complet](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md)** pour vous aider à gérer votre contenu multilingue en **temps réel**, rendant la collaboration avec les traducteurs, les rédacteurs et les autres membres de l'équipe transparente. Le contenu peut être stocké localement et/ou à distance.
+
+</Accordion>
+
+</AccordionGroup>
+
+---
+
+## Stratégies de migration
+
+Il existe deux stratégies complémentaires pour migrer de `vue-i18n` à Intlayer :
+
+1. **Adaptateur de compatibilité (recommandé pour les applications existantes)** — Installez `@intlayer/vue-i18n` (pour les composants Vue). Ce package expose **exactement la même API** que `vue-i18n` mais délègue tout le travail de traduction à Intlayer en coulisses. Vous conservez vos appels existants à `$t`, `useI18n()`, et `<i18n-t>` — le seul changement est le chemin d'importation et l'initialisation.
+
+2. **Migration complète** — Remplacez progressivement les API `vue-i18n` par des hooks natifs Intlayer (`useIntlayer`) et colocalisez le contenu dans des fichiers `.content.ts` avec vos composants.
+
+Ce guide couvre d'abord la **Stratégie 1** (adaptateur de compatibilité prêt à l'emploi), puis passe en revue la migration complète optionnelle.
+
+---
+
+## Table des Matières
+
+<TOC/>
+
+---
+
+## Migration rapide
+
+Les étapes suivantes sont le minimum requis pour faire fonctionner votre application `vue-i18n` existante sur Intlayer avec zéro changement de code dans vos composants.
+
+<Steps>
+
+<Step number={1} title="Installer les Dépendances">
+
+Installez les packages principaux d'Intlayer et l'adaptateur de compatibilité :
+
+```bash packageManager="npm"
+npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
+bun x intlayer init
+```
+
+> Vous pouvez garder `vue-i18n` installé — l'adaptateur de compatibilité l'utilise comme `devDependency` / `peerDependency` pour les types TypeScript.
+
+</Step>
+
+<Step number={2} title="Configurer Intlayer">
+
+La commande `intlayer init` crée un fichier `intlayer.config.ts` de démarrage. Mettez-le à jour pour qu'il corresponde à vos paramètres régionaux existants et pointez le plugin `syncJSON` sur vos fichiers de messages :
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Ajoutez tous vos paramètres régionaux existants ici
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      // correspond à la syntaxe d'espace réservé vue-i18n : {name}
+      format: "icu",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+};
+
+export default config;
+```
+
+> **`source`** mappe un paramètre régional à son chemin de fichier JSON. **`location`** indique à l'observateur Intlayer quel dossier surveiller pour les modifications. L'option `format: 'icu'` garantit que les espaces réservés sont analysés correctement pour `vue-i18n`.
+
+</Step>
+
+<Step number={3} title="Ajouter le Plugin Intlayer à votre Bundler">
+
+Enveloppez votre configuration de bundler existante avec le plugin de compatibilité. Il compose le plugin Intlayer de base, configure la surveillance du contenu, et — point critique — **injecte un alias de module** afin que vos appels existants `import … from 'vue-i18n'` soient redirigés de manière transparente vers `@intlayer/vue-i18n` lors de la construction. Aucun changement de fichier source n'est nécessaire.
+
+**Pour Vite :**
+
+```typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+> `vueI18nVitePlugin()` enveloppe le plugin `intlayer()` de `vite-intlayer` et ajoute l'alias `vue-i18n`. L'utilisation du simple plugin `intlayer()` de `vite-intlayer` compile les dictionnaires mais n'ajoute **pas** l'alias — vous devrez alors renommer les imports vers `@intlayer/vue-i18n` manuellement (voir l'étape 4).
+
+**Pour Nuxt :**
+
+Si vous utilisez `@nuxtjs/i18n` (intégration Nuxt), installez `nuxt-intlayer` et ajoutez-le à votre `nuxt.config.ts` :
+
+```bash packageManager="npm"
+npm install nuxt-intlayer
+```
+
+```typescript fileName="nuxt.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+export default defineNuxtConfig({
+  modules: ["nuxt-intlayer"],
+  // Vous pouvez supprimer en toute sécurité @nuxtjs/i18n de vos modules
+});
+```
+
+> **Vous n'avez plus besoin de `createI18n()` ou du bootstrap manuel du provider.** Intlayer compile tous les dictionnaires **au moment de la construction**, il n'y a donc pas d'étape de chargement à l'exécution. Le provider aliasé gère l'initialisation pour vous.
+
+</Step>
+
+</Steps>
+
+C'est tout pour la migration rapide. Votre application fonctionne désormais sur Intlayer tout en conservant chaque import et API `vue-i18n` intacts.
+
+> **Clés de traduction typées — automatiques.** Une fois qu'Intlayer a compilé vos dictionnaires, `useI18n` est typé par rapport à votre contenu réel lorsque vous passez une option `namespace`. Les clés sont autocomplétées dans votre IDE et les chemins invalides provoquent des erreurs TypeScript au moment de la construction — aucune configuration supplémentaire n'est requise.
+>
+> ```ts
+> // 'about' est une clé de dictionnaire enregistrée
+> const { t } = useI18n({ namespace: "about" });
+> t("counter.label"); // ✓ autocomplété
+> t("does.not.exist"); // ✗ Erreur TypeScript
+> ```
+
+---
+
+## Migration complète
+
+Les étapes ci-dessous sont facultatives et peuvent être effectuées de manière incrémentielle. Elles débloquent l'ensemble des fonctionnalités d'Intlayer : éditeur visuel, CMS, fichiers de contenu typés, traduction alimentée par l'IA, et plus encore.
+
+<Steps>
+
+<Step number={4} title="Renommage explicite des imports (optionnel)" isOptional={true}>
+
+Les plugins Intlayer gèrent déjà l'aliassage au niveau du bundler. Si vous préférez rendre la dépendance explicite dans vos fichiers sources, vous pouvez renommer les imports manuellement :
+
+| Avant                                   | Après                                             |
+| --------------------------------------- | ------------------------------------------------- |
+| `import { useI18n } from 'vue-i18n'`    | `import { useI18n } from '@intlayer/vue-i18n'`    |
+| `import { createI18n } from 'vue-i18n'` | `import { createI18n } from '@intlayer/vue-i18n'` |
+
+Ce sont des **remplacements directs** — aucun changement de signatures d'appel, d'arguments ou de types de retour n'est requis.
+
+</Step>
+
+<Step number={5} title="Activer l'automatisation de la traduction alimentée par l'IA" isOptional={true}>
+
+Une fois Intlayer configuré, utilisez sa CLI pour remplir automatiquement les traductions manquantes :
+
+```bash packageManager="npm"
+# Tester les traductions manquantes (ajouter au CI)
+npx intlayer test
+
+# Remplir les traductions manquantes avec l'IA
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer test
+pnpm intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn intlayer test
+yarn intlayer fill
+```
+
+```bash packageManager="bun"
+bun x intlayer test
+bun x intlayer fill
+```
+
+Ajoutez la configuration de l'IA à `intlayer.config.ts` :
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./src/locales/${locale}.json`,
+      location: "src/locales",
+    }),
+  ],
+  ai: {
+    apiKey: process.env.OPENAI_API_KEY,
+    // provider: "openai",     // défaut
+    // model: "gpt-4o-mini",   // défaut
+  },
+};
+
+export default config;
+```
+
+> Consultez la [documentation de la CLI Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/index.md) pour toutes les options disponibles.
+
+</Step>
+
+</Steps>
+
+---
+
+## Ce que vous pouvez supprimer après la migration
+
+Une fois les adaptateurs de compatibilité en place, le code standard `vue-i18n` suivant peut être supprimé :
+
+| Fichier / modèle                               | Pourquoi ce n'est plus nécessaire                                                                                                                                                       |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| appels `createI18n()`                          | Le provider d'Intlayer initialise tout automatiquement ; il n'y a pas d'étape de chargement à l'exécution.                                                                              |
+| Enregistrement du plugin Vue (`app.use(i18n)`) | Le plugin Intlayer gère l'injection et le bootstrap en coulisses.                                                                                                                       |
+| Bundles de langue JSON (`locales/*.json`)      | Les bundles JSON ne sont nécessaires que si vous utilisez encore le plugin `syncJSON`. Une fois que vous migrez vers des fichiers `.content.ts`, vous pouvez supprimer le dossier JSON. |
+
+Lorsque vous êtes prêt à aller plus loin, Intlayer **découvre automatiquement tous les fichiers `.content.ts` et `.content.json` n'importe où dans votre base de code** (par défaut, n'importe où dans `./src`). Vous pouvez placer un fichier `my-component.content.ts` juste à côté de votre `MyComponent.vue` et Intlayer le détectera au moment de la construction sans configuration supplémentaire — pas d'imports, pas d'enregistrement, pas besoin de fichier d'index centralisé. Cela rend la colocalisation des traductions avec les pages et les composants complètement transparente.
+
+---
+
+## Configurer TypeScript
+
+Intlayer utilise l'augmentation de module pour fournir une intellisense TypeScript complète pour vos clés de traduction. Assurez-vous que votre `tsconfig.json` inclut les types générés automatiquement :
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Vos configurations TypeScript existantes
+  "include": [
+    // ... Vos configurations TypeScript existantes
+    ".intlayer/**/*.ts", // Inclure les types générés automatiquement
+  ],
+}
+```
+
+---
+
+## Configuration Git
+
+Ajoutez le répertoire généré par Intlayer à votre `.gitignore` :
+
+```plaintext fileName=".gitignore"
+# Ignorer les fichiers générés par Intlayer
+.intlayer
+```
+
+---
+
+## Aller plus loin
+
+- **Éditeur visuel** — Gérez les traductions visuellement dans votre navigateur : [Éditeur visuel Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_visual_editor.md)
+- **CMS** — Externalisez et gérez le contenu à distance : [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md)
+- **Extension VS Code** — Obtenez l'autocomplétion et la détection d'erreurs de traduction en temps réel : [Extension VS Code Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/vs_code_extension.md)
+- **Référence CLI** — Liste complète des commandes CLI : [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/index.md)
+- **Intlayer avec Vue** — Guide d'installation complet pour Vue : [intlayer_with_vite+vue.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_with_vite+vue.md)
+- **Intlayer avec Nuxt** — Guide d'installation complet pour Nuxt : [intlayer_with_nuxt.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_with_nuxt.md)

package/docs/fr/packages/react-intlayer/index.md

@@ -62,7 +62,7 @@ bun x intlayer init
 
 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,cjs}`.
+Par défaut, Intlayer recherche les fichiers avec l'extension `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`.
 
 > Vous pouvez modifier l'extension par défaut en configurant la propriété `contentDir` dans le [fichier de configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md).