@intlayer/docs 8.9.3 → 8.9.4

package/docs/fr/plugins/sync-po.md

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Plugin Sync PO
+description: Synchronisez les dictionnaires Intlayer avec les fichiers Gettext PO. Conservez votre i18n existante tout en utilisant Intlayer pour gérer, traduire et tester vos messages.
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - traductions
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Documentation initiale du plugin Sync PO"
+---
+
+# Sync PO (ponts i18n) - Sync PO avec support ICU / i18next
+
+Utilisez Intlayer comme un complément à votre stack i18n existante. Ce plugin maintient vos messages Gettext PO synchronisés avec les dictionnaires Intlayer afin que vous puissiez :
+
+- Conserver votre workflow de traduction basé sur PO existant.
+- Gérer et traduire vos messages avec Intlayer (CLI, CI, fournisseurs, CMS), sans refactoriser votre application.
+- Publier des tutoriels et du contenu SEO ciblant chaque écosystème, tout en suggérant Intlayer comme couche de gestion PO.
+
+Notes et portée actuelle :
+
+- L'externalisation vers le CMS fonctionne pour les traductions et le texte classique.
+- Pas encore de support pour les insertions, les pluriels/ICU ou les fonctionnalités avancées au moment de l'exécution d'autres bibliothèques au sein des entrées PO elles-mêmes.
+- L'éditeur visuel n'est pas encore supporté pour les sorties i18n tierces.
+
+### Quand utiliser ce plugin
+
+- Vous utilisez déjà des fichiers Gettext PO pour vos traductions.
+- Vous souhaitez bénéficier du remplissage assisté par IA, des tests en CI et des opérations de contenu sans changer votre runtime de rendu.
+
+## Installation
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# ou
+npm i -D @intlayer/sync-po-plugin
+```
+
+## Plugins
+
+Ce package fournit deux plugins :
+
+- `loadPO` : Charge les fichiers PO dans les dictionnaires Intlayer.
+  - Ce plugin est utilisé pour charger des fichiers PO à partir d'une source et les intégrer dans les dictionnaires Intlayer. Il peut scanner toute la base de code et rechercher des fichiers PO spécifiques.
+    Ce plugin peut être utilisé :
+    - si vous utilisez une bibliothèque i18n qui impose un emplacement spécifique pour le chargement de vos fichiers PO, mais que vous souhaitez placer votre déclaration de contenu où vous le souhaitez dans votre base de code.
+    - Il peut également être utilisé si vous souhaitez récupérer vos messages à partir d'une source distante (ex : un CMS, une API, etc.) et stocker vos messages dans des fichiers PO.
+
+  > Sous le capot, ce plugin scannera toute la base de code, recherchera des fichiers PO spécifiques et les chargera dans les dictionnaires Intlayer.
+  > Notez que ce plugin n'écrira pas la sortie et les traductions en retour dans les fichiers PO.
+
+- `syncPO` : Synchronise les fichiers PO avec les dictionnaires Intlayer.
+  - Ce plugin est utilisé pour synchroniser les fichiers PO avec les dictionnaires Intlayer. Il peut scanner l'emplacement donné et charger les PO qui correspondent au motif pour des fichiers PO spécifiques. Ce plugin est utile si vous souhaitez bénéficier des avantages d'Intlayer tout en utilisant une autre bibliothèque i18n.
+
+## Utilisation des deux plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO, syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Gardez vos fichiers PO actuels synchronisés avec les dictionnaires Intlayer
+  plugins: [
+    /**
+     * Chargera tous les fichiers PO dans le src qui correspondent au motif {key}.i18n.po
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Garantit que ces fichiers PO ont la priorité sur les fichiers à `./locales/en/${key}.po`
+    }),
+    /**
+     * Chargera et écrira la sortie et les traductions en retour dans les fichiers PO du répertoire locales
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin `syncPO`
+
+### Démarrage rapide
+
+Ajoutez le plugin à votre `intlayer.config.ts` et pointez-le vers votre structure PO existante.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Gardez vos fichiers PO actuels synchronisés avec les dictionnaires Intlayer
+  plugins: [
+    syncPO({
+      // Mise en page par langue, par espace de noms
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternative : un seul fichier par langue :
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncPO({
+      source: ({ locale }) => `./locales/${locale}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+#### Comment ça marche
+
+- Lecture : le plugin découvre les fichiers PO à partir de votre constructeur `source` et les charge en tant que dictionnaires Intlayer.
+- Écriture : après les constructions et les remplissages, il réécrit les PO localisés dans les mêmes chemins (avec les en-têtes Gettext appropriés).
+- Auto-remplissage : le plugin déclare un chemin `autoFill` pour chaque dictionnaire. L'exécution de `intlayer fill` met à jour uniquement les traductions manquantes dans vos fichiers PO par défaut.
+
+API :
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // requis
+  location?: string, // étiquette optionnelle, défaut : "sync-po::path/to/source"
+  priority?: number, // priorité optionnelle pour la résolution de conflits, défaut : 0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // optionnel, nécessaire uniquement lorsque vos valeurs msgstr utilisent une syntaxe d'interpolation spécifique
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+Les fichiers PO sont toujours des fichiers Gettext Portable Object — c'est fixe. Cette option décrit uniquement la **syntaxe d'interpolation** utilisée à l'intérieur des valeurs `msgstr`, afin qu'Intlayer puisse les convertir dans son propre format au moment de l'analyse (via `formatDictionary`) et inversement lors de l'écriture de la sortie.
+
+- `undefined` _(défaut)_ : les valeurs `msgstr` sont traitées comme des chaînes de caractères simples — pas de transformation. Utilisez ceci pour la plupart des fichiers PO.
+- `'icu'` : les valeurs `msgstr` utilisent la syntaxe de message ICU (ex : `{count, plural, one {# item} other {# items}}`).
+- `'i18next'` : les valeurs `msgstr` utilisent la syntaxe d'interpolation i18next (ex : `{{variable}}`).
+- `'vue-i18n'` : les valeurs `msgstr` utilisent la syntaxe Vue I18n.
+
+> La transformation est appliquée par `formatDictionary` de `@intlayer/chokidar` au chargement, et inversée avec `formatDictionaryOutput` à l'écriture. Pour les règles complexes comme les pluriels ICU, la fidélité de l'aller-retour n'est pas garantie.
+
+**Exemple — les fichiers PO contiennent une interpolation de style i18next :**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### Sources PO multiples et priorité
+
+Vous pouvez ajouter plusieurs plugins `syncPO` pour synchroniser différentes sources PO. Ceci est utile lorsque vous avez plusieurs sources de traduction ou différentes structures PO dans votre projet.
+
+#### Système de priorité
+
+Lorsque plusieurs plugins ciblent la même clé de dictionnaire, le paramètre `priority` détermine quel plugin prime :
+
+- Les numéros de priorité plus élevés l'emportent sur les plus bas
+- La priorité par défaut des fichiers `.content` est `0`
+- La priorité par défaut des plugins est `0`
+- Les plugins ayant la même priorité sont traités dans l'ordre où ils apparaissent dans la configuration
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Source PO principale (priorité la plus élevée)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Source PO de secours (priorité plus basse)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Source PO héritée (priorité la plus basse)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin Load PO
+
+### Démarrage rapide
+
+Ajoutez le plugin à votre `intlayer.config.ts` pour ingérer des fichiers PO existants en tant que dictionnaires Intlayer. Ce plugin est en lecture seule (pas d'écriture sur le disque) :
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Ingérer les messages PO situés n'importe où dans votre arborescence source
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // Charger une seule langue par instance de plugin (par défaut la langue par défaut de la configuration)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternative : mise en page par langue, toujours en lecture seule (seule la langue sélectionnée est chargée) :
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadPO({
+      // Seuls les fichiers pour Locales.FRENCH seront chargés à partir de ce motif
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Comment ça marche
+
+- Découverte : construit un glob à partir de votre constructeur `source` et collecte les fichiers PO correspondants.
+- Ingestion : charge chaque fichier PO en tant que dictionnaire Intlayer avec la `locale` fournie.
+- Lecture seule : n'écrit ni ne formate les fichiers de sortie ; utilisez `syncPO` si vous avez besoin d'une synchronisation aller-retour.
+- Prêt pour l'auto-remplissage : définit un chemin `fill` afin que `intlayer content fill` puisse peupler les clés manquantes.
+
+### API
+
+```ts
+loadPO({
+  // Construire les chemins vers vos PO. `locale` est optionnel si votre structure n'a pas de segment de langue
+  source: ({ key, locale }) => string,
+
+  // Langue cible pour les dictionnaires chargés par cette instance de plugin
+  // Par défaut configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Étiquette optionnelle pour identifier la source
+  location?: string, // défaut : "plugin"
+
+  // Priorité utilisée pour la résolution de conflits avec d'autres sources
+  priority?: number, // défaut : 0
+});
+```
+
+### Comportement et conventions
+
+- Si votre masque `source` inclut un espace réservé pour la langue, seuls les fichiers pour la `locale` sélectionnée sont ingérés.
+- S'il n'y a pas de segment `{key}` dans votre masque, la clé du dictionnaire est "index".
+- Les clés sont dérivées des chemins de fichiers en remplaçant l'espace réservé `{key}` dans votre constructeur `source`.
+- Le plugin utilise uniquement les fichiers découverts et ne fabrique pas de langues ou de clés manquantes.
+- Le chemin `fill` est déduit de votre `source` et utilisé pour mettre à jour les valeurs manquantes via CLI lorsque vous l'acceptez.
+
+## Résolution de conflits
+
+Lorsque la même clé de traduction existe dans plusieurs sources PO :
+
+1. Le plugin ayant la priorité la plus élevée détermine la valeur finale
+2. Les sources de priorité inférieure sont utilisées comme secours pour les clés manquantes
+3. Cela vous permet de conserver les traductions héritées tout en migrant progressivement vers de nouvelles structures
+
+## CLI
+
+Les fichiers PO synchronisés seront considérés comme les autres fichiers `.content`. Cela signifie que toutes les commandes intlayer seront disponibles pour les fichiers PO synchronisés. Y compris :
+
+- `intlayer content test` pour tester s'il y a des traductions manquantes
+- `intlayer content list` pour lister les fichiers PO synchronisés
+- `intlayer content fill` pour remplir les traductions manquantes
+- `intlayer content push` pour pousser les fichiers PO synchronisés
+- `intlayer content pull` pour tirer les fichiers PO synchronisés
+
+Voir [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) pour plus de détails.
+
+## Limitations (actuelles)
+
+- Pas de support pour les insertions ou les pluriels/ICU lors du ciblage de bibliothèques tierces.
+- L'éditeur visuel n'est pas encore disponible pour les runtimes non-Intlayer.
+- Synchronisation PO uniquement ; les formats de catalogue non-PO ne sont pas supportés.
+
+## Pourquoi c'est important
+
+- Nous pouvons recommander des solutions i18n établies et positionner Intlayer comme un complément.
+- Nous exploitons leur SEO/mots-clés avec des tutoriels qui se terminent par la suggestion d'utiliser Intlayer pour gérer les PO.
+- Étend l'audience adressable des « nouveaux projets » à « toute équipe utilisant déjà i18n ».

package/docs/hi/mcp_server.md

@@ -23,7 +23,7 @@ history:
     changes: "Claude Desktop सेट अप जोड़ा"
   - version: 5.5.12
     date: 2025-07-10
-    changes: "SSE ट्रांसपोर्ट और दूरस्थ सर्वर जोड़ा"
+    changes: "Streamable HTTP ट्रांसपोर्ट और दूरस्थ सर्वर जोड़ा"
   - version: 5.5.10
     date: 2025-06-29
     changes: "इतिहास प्रारंभ करें"
@@ -51,12 +51,12 @@ Intlayer MCP सर्वर को अपने IDE में सक्षम
 
   > कमांड्स और विकल्पों की पूरी सूची देखने के लिए [Intlayer CLI दस्तावेज़ीकरण](https://github.com/aymericzip/intlayer/blob/main/docs/docs/hi/cli/index.md) देखें।
 
-## लोकल सर्वर (stdio) बनाम रिमोट सर्वर (SSE)
+## लोकल सर्वर (stdio) बनाम रिमोट सर्वर (Streamable HTTP)
 
 MCP सर्वर का उपयोग दो तरीकों से किया जा सकता है:
 
 - लोकल सर्वर (stdio)
-- रिमोट सर्वर (SSE)
+- रिमोट सर्वर (Streamable HTTP)
 
 ### लोकल सर्वर (stdio) (सिफारिश की गई)
 
@@ -64,9 +64,9 @@ Intlayer एक NPM पैकेज प्रदान करता है ज
 
 यह सर्वर MCP सर्वर का उपयोग करने का सिफारिश किया गया तरीका है। क्योंकि यह MCP सर्वर की सभी सुविधाओं को एकीकृत करता है, जिसमें CLI टूल्स भी शामिल हैं।
 
-### रिमोट सर्वर (SSE)
+### रिमोट सर्वर (Streamable HTTP)
 
-MCP सर्वर को दूरस्थ रूप से भी उपयोग किया जा सकता है, SSE ट्रांसपोर्ट विधि का उपयोग करके। यह सर्वर Intlayer द्वारा होस्ट किया जाता है, और https://mcp.intlayer.org पर उपलब्ध है। इस सर्वर तक सार्वजनिक रूप से, बिना किसी प्रमाणीकरण के पहुंचा जा सकता है, और यह उपयोग के लिए मुफ्त है।
+MCP सर्वर को दूरस्थ रूप से भी उपयोग किया जा सकता है, Streamable HTTP ट्रांसपोर्ट विधि का उपयोग करके। यह सर्वर Intlayer द्वारा होस्ट किया जाता है, और https://mcp.intlayer.org पर उपलब्ध है। इस सर्वर तक सार्वजनिक रूप से, बिना किसी प्रमाणीकरण के पहुंचा जा सकता है, और यह उपयोग के लिए मुफ्त है।
 
 ध्यान दें कि रिमोट सर्वर CLI टूल्स, AI ऑटोकम्प्लीशन आदि को एकीकृत नहीं करता है। दूरस्थ सर्वर केवल दस्तावेज़ीकरण के साथ इंटरैक्शन के लिए है ताकि आपका AI असिस्टेंट Intlayer इकोसिस्टम में मदद कर सके।
 
@@ -97,7 +97,7 @@ bun x intlayer init mcp
 यह कमांड:
 
 1. आपसे पूछेगा कि आप किस प्लेटफॉर्म का उपयोग कर रहे हैं (Cursor, VS Code, Claude Desktop, आदि)।
-2. आपसे पूछेगा कि आप किस ट्रांसपोर्ट विधि का उपयोग करना चाहते हैं (लोकल सर्वर (stdio) या रिमोट सर्वर (SSE))।
+2. आपसे पूछेगा कि आप किस ट्रांसपोर्ट विधि का उपयोग करना चाहते हैं (लोकल सर्वर (stdio) या रिमोट सर्वर (Streamable HTTP))।
 3. आपकी कॉन्फ़िगरेशन फ़ाइल (जैसे, `.cursor/mcp.json`, `.vscode/mcp.json`, या ग्लोबल Claude Desktop कॉन्फ़िगरेशन) को स्वचालित रूप से अपडेट करेगा।
 
 ---
@@ -107,7 +107,7 @@ bun x intlayer init mcp
 1. कमांड पैलेट खोलें (Ctrl+Shift+P या Cmd+Shift+P)।
 2. `Intlayer: Setup AI Agent Skills` टाइप करें।
 3. वह प्लेटफॉर्म चुनें जिसका आप उपयोग करते हैं (जैसे `VS Code`, `Cursor`, `Windsurf`, `OpenCode`, `Claude Code`, `GitHub Copilot Workspace`, आदि)।
-4. इंस्टॉल करने के लिए MCP चुनें (stdio, SSE)।
+4. इंस्टॉल करने के लिए MCP चुनें (stdio, Streamable HTTP)।
 5. Enter दबाएं।
 
 ---
@@ -131,16 +131,16 @@ Cursor में MCP सर्वर को कॉन्फ़िगर कर
 }
 ```
 
-### रिमोट सर्वर (SSE)
+### रिमोट सर्वर (Streamable HTTP)
 
-रिमोट Intlayer MCP सर्वर से Server-Sent Events (SSE) का उपयोग करके कनेक्ट करने के लिए, आप अपने MCP क्लाइंट को होस्टेड सेवा से कनेक्ट करने के लिए कॉन्फ़िगर कर सकते हैं।
+रिमोट Intlayer MCP सर्वर से Server-Sent Events (Streamable HTTP) का उपयोग करके कनेक्ट करने के लिए, आप अपने MCP क्लाइंट को होस्टेड सेवा से कनेक्ट करने के लिए कॉन्फ़िगर कर सकते हैं।
 
 ```json fileName=".cursor/mcp.json"
 {
   "mcpServers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "transport": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -172,16 +172,16 @@ VS Code के साथ Intlayer MCP सर्वर का उपयोग क
 }
 ```
 
-### रिमोट सर्वर (SSE)
+### रिमोट सर्वर (Streamable HTTP)
 
-रिमोट Intlayer MCP सर्वर से Server-Sent Events (SSE) का उपयोग करके कनेक्ट करने के लिए, आप अपने MCP क्लाइंट को होस्टेड सेवा से कनेक्ट करने के लिए कॉन्फ़िगर कर सकते हैं।
+रिमोट Intlayer MCP सर्वर से Server-Sent Events (Streamable HTTP) का उपयोग करके कनेक्ट करने के लिए, आप अपने MCP क्लाइंट को होस्टेड सेवा से कनेक्ट करने के लिए कॉन्फ़िगर कर सकते हैं।
 
 ```json fileName=".vscode/mcp.json"
 {
   "servers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "type": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -191,7 +191,7 @@ VS Code के साथ Intlayer MCP सर्वर का उपयोग क
 
 ## ChatGPT में सेटअप
 
-### रिमोट सर्वर (SSE)
+### रिमोट सर्वर (Streamable HTTP)
 
 ChatGPT में MCP सर्वर को कॉन्फ़िगर करने के लिए [आधिकारिक दस्तावेज़](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) का पालन करें।
 
@@ -232,6 +232,19 @@ Claude Desktop में MCP सर्वर कॉन्फ़िगर कर
 }
 ```
 
+### रिमोट सर्वर (Streamable HTTP)
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## CLI के माध्यम से MCP सर्वर का उपयोग करना