@intlayer/docs 8.4.10 → 8.5.1

package/docs/fr/intlayer_with_vite+lit.md

@@ -0,0 +1,698 @@
+---
+createdAt: 2026-03-23
+updatedAt: 2026-03-23
+title: i18n Vite + Lit - Comment traduire une application Lit en 2026
+description: Découvrez comment rendre votre site web Vite et Lit multilingue. Suivez la documentation pour l'internationaliser (i18n) et le traduire.
+keywords:
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Vite
+  - Lit
+  - Web Components
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - vite-and-lit
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-lit-template
+history:
+  - version: 8.4.10
+    date: 2026-03-23
+    changes: "Init history"
+---
+
+# Traduisez votre site web Vite et Lit en utilisant Intlayer | Internationalisation (i18n)
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-vite-lit-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+## Table des matières
+
+<TOC/>
+
+## Qu'est-ce qu'Intlayer ?
+
+**Intlayer** est une bibliothèque d'internationalisation (i18n) innovante et open-source conçue pour simplifier le support multilingue dans les applications web modernes.
+
+Avec Intlayer, vous pouvez :
+
+- **Gérer facilement les traductions** en utilisant des dictionnaires déclaratifs au niveau des composants.
+- **Localiser dynamiquement les métadonnées**, les routes et le contenu.
+- **Assurer le support TypeScript** avec des types autogénérés, améliorant l'autocomplétion et la détection d'erreurs.
+- **Bénéficier de fonctionnalités avancées**, comme la détection et le changement dynamique de langue.
+
+---
+
+## Guide étape par étape pour configurer Intlayer dans une application Vite et Lit
+
+### Étape 1 : Installer les dépendances
+
+Installez les paquets nécessaires en utilisant npm :
+
+```bash packageManager="npm"
+npm install intlayer lit-intlayer
+npm install vite-intlayer --save-dev
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer lit-intlayer
+pnpm add vite-intlayer --save-dev
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer lit-intlayer
+yarn add vite-intlayer --save-dev
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer lit-intlayer
+bun add vite-intlayer --dev
+bunx intlayer init
+```
+
+- **intlayer**
+
+  Le paquet principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la [déclaration de contenu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/content_file.md), la transpilation et les [commandes CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/index.md).
+
+- **lit-intlayer**
+  Le paquet qui intègre Intlayer aux applications Lit. Il fournit des hooks basés sur `ReactiveController` (`useIntlayer`, `useLocale`, etc.) pour que les LitElements se re-rendent automatiquement lorsque la langue change.
+
+- **vite-intlayer**
+  Comprend le plugin Vite pour intégrer Intlayer avec le [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), ainsi qu'un middleware pour détecter la langue préférée de l'utilisateur, gérer les cookies et gérer la redirection d'URL.
+
+### Étape 2 : Configuration de votre projet
+
+Créez un fichier de configuration pour configurer les langues de votre application :
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Vos autres langues
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Vos autres langues
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Vos autres langues
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> Via ce fichier de configuration, vous pouvez configurer les URL localisées, la redirection du middleware, les noms des cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et plus encore. Pour une liste complète des paramètres disponibles, reportez-vous à la [documentation de configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/configuration.md).
+
+### Étape 3 : Intégrer Intlayer dans votre configuration Vite
+
+Ajoutez le plugin intlayer dans votre configuration.
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+```javascript fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+```javascript fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { intlayer } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+> Le plugin Vite `intlayer()` est utilisé pour intégrer Intlayer avec Vite. Il assure la construction des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer dans l'application Vite. De plus, il fournit des alias pour optimiser les performances.
+
+### Étape 4 : Initialiser Intlayer dans votre point d'entrée
+
+Appelez `installIntlayer()` **avant** que les éléments personnalisés ne soient enregistrés pour que le singleton global de langue soit prêt lorsque le premier élément se connecte.
+
+```typescript fileName="src/main.ts" codeFormat="typescript"
+import { installIntlayer } from "lit-intlayer";
+
+// Doit être appelé avant qu'un LitElement ne soit connecté au DOM.
+installIntlayer();
+
+// Importez et enregistrez vos éléments personnalisés.
+import "./my-element.js";
+```
+
+Si vous utilisez également des déclarations de contenu `md()` (Markdown), installez également le moteur de rendu markdown :
+
+```typescript fileName="src/main.ts" codeFormat="typescript"
+import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";
+
+installIntlayer();
+installIntlayerMarkdown();
+
+import "./my-element.js";
+```
+
+### Étape 5 : Déclarer votre contenu
+
+Créez et gérez vos déclarations de contenu pour stocker les traductions :
+
+```typescript fileName="src/app.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: "Vite + Lit",
+
+    viteLogo: t({
+      en: "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    litLogo: t({
+      en: "Lit logo",
+      fr: "Logo Lit",
+      es: "Logo Lit",
+    }),
+
+    count: t({
+      en: "count is {{count}}",
+      fr: "le compte est {{count}}",
+      es: "el recuento es {{count}}",
+    }),
+
+    readTheDocs: t({
+      en: "Click on the Vite and Lit logos to learn more",
+      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
+      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```javascript fileName="src/app.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    title: "Vite + Lit",
+
+    viteLogo: t({
+      en: "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    litLogo: t({
+      en: "Lit logo",
+      fr: "Logo Lit",
+      es: "Logo Lit",
+    }),
+
+    count: t({
+      en: "count is {{count}}",
+      fr: "le compte est {{count}}",
+      es: "el recuento es {{count}}",
+    }),
+
+    readTheDocs: t({
+      en: "Click on the Vite and Lit logos to learn more",
+      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
+      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
+    }),
+  },
+};
+
+export default appContent;
+```
+
+```javascript fileName="src/app.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    title: "Vite + Lit",
+
+    viteLogo: t({
+      en: "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    litLogo: t({
+      en: "Lit logo",
+      fr: "Logo Lit",
+      es: "Logo Lit",
+    }),
+
+    count: t({
+      en: "count is {{count}}",
+      fr: "le compte est {{count}}",
+      es: "el recuento es {{count}}",
+    }),
+
+    readTheDocs: t({
+      en: "Click on the Vite and Lit logos to learn more",
+      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
+      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
+    }),
+  },
+};
+
+module.exports = appContent;
+```
+
+```json fileName="src/app.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "app",
+  "content": {
+    "title": "Vite + Lit",
+    "viteLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Vite logo",
+        "fr": "Logo Vite",
+        "es": "Logo Vite"
+      }
+    },
+    "litLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Lit logo",
+        "fr": "Logo Lit",
+        "es": "Logo Lit"
+      }
+    },
+    "count": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "count is {{count}}",
+        "fr": "le compte est {{count}}",
+        "es": "el recuento es {{count}}"
+      }
+    },
+    "readTheDocs": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Click on the Vite and Lit logos to learn more",
+        "fr": "Cliquez sur les logos Vite et Lit pour en savoir plus",
+        "es": "Haga clic en los logotipos de Vite y Lit para obtener más información"
+      }
+    }
+  }
+}
+```
+
+> Vos déclarations de contenu peuvent être définies n'importe où dans votre application dès qu'elles sont incluses dans le répertoire `contentDir` (par défaut, `./src`) et correspondent à l'extension du fichier de déclaration de contenu (par défaut, `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+>
+> Pour plus de détails, reportez-vous à la [documentation sur la déclaration de contenu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/dictionary/content_file.md).
+
+### Étape 6 : Utiliser Intlayer dans votre LitElement
+
+Utilisez `useIntlayer` à l'intérieur d'un `LitElement`. Il renvoie un proxy `ReactiveController` qui déclenche automatiquement des re-rendus dès que la langue active change — aucune configuration supplémentaire n'est requise.
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+import { LitElement, html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { useIntlayer } from "lit-intlayer";
+
+@customElement("my-element")
+export class MyElement extends LitElement {
+  @property({ type: Number })
+  count = 0;
+
+  // useIntlayer s'enregistre en tant que ReactiveController.
+  // L'élément se re-rend automatiquement lorsque la langue change.
+  private content = useIntlayer(this, "app");
+
+  override render() {
+    const { content } = this;
+
+    return html`
+      <h1>${content.title}</h1>
+
+      <img src="/vite.svg" alt=${content.viteLogo.value} />
+      <img src="/lit.svg" alt=${content.litLogo.value} />
+
+      <button @click=${() => this.count++}>
+        ${content.count({ count: this.count })}
+      </button>
+
+      <p>${content.readTheDocs}</p>
+    `;
+  }
+}
+```
+
+> [!NOTE]
+> Lorsque vous avez besoin de la chaîne traduite dans un attribut HTML natif (ex: `alt`, `aria-label`, `title`), appelez `.value` sur le nœud terminal :
+>
+> ```typescript
+> html`<img alt=${content.viteLogo.value} />`;
+> ```
+
+### (Optionnel) Étape 7 : Changer la langue de votre contenu
+
+Pour changer la langue de votre contenu, utilisez la méthode `setLocale` exposée par le contrôleur `useLocale`.
+
+```typescript fileName="src/locale-switcher.ts" codeFormat="typescript"
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { getLocaleName } from "intlayer";
+import { useLocale } from "lit-intlayer";
+
+@customElement("locale-switcher")
+export class LocaleSwitcher extends LitElement {
+  private locale = useLocale(this);
+
+  private _onChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    this.locale.setLocale(select.value as any);
+  }
+
+  override render() {
+    return html`
+      <select @change=${this._onChange}>
+        ${this.locale.availableLocales.map(
+          (loc) => html`
+            <option value=${loc} ?selected=${loc === this.locale.locale}>
+              ${getLocaleName(loc)}
+            </option>
+          `
+        )}
+      </select>
+    `;
+  }
+}
+```
+
+### (Optionnel) Étape 8 : Rendre du contenu Markdown et HTML
+
+Intlayer prend en charge les déclarations de contenu `md()` et `html()`. Dans Lit, le résultat compilé est injecté en tant que HTML brut via la directive `unsafeHTML`.
+
+```typescript fileName="src/app.content.ts" contentDeclarationFormat="typescript"
+import { md, t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    // ...
+    editNote: md(
+      t({
+        en: "Edit `src/my-element.ts` and save to test **HMR**",
+        fr: "Modifiez `src/my-element.ts` et enregistrez pour tester **HMR**",
+        es: "Edite `src/my-element.ts` y guarde para probar **HMR**",
+      })
+    ),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+Rendez le HTML compilé dans votre élément :
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { useIntlayer } from "lit-intlayer";
+import { compileMarkdown } from "lit-intlayer/markdown";
+
+@customElement("my-element")
+export class MyElement extends LitElement {
+  private content = useIntlayer(this, "app");
+
+  override render() {
+    return html`
+      <div class="edit-note">
+        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}
+      </div>
+    `;
+  }
+}
+```
+
+> [!TIP]
+> `String(content.editNote)` appelle `toString()` sur l'`IntlayerNode`, qui renvoie la chaîne Markdown brute. Passez-la à `compileMarkdown` pour obtenir une chaîne HTML, puis rendez-la avec la directive `unsafeHTML` de Lit.
+
+### (Optionnel) Étape 9 : Ajouter le routage localisé à votre application
+
+Pour créer des routes uniques pour chaque langue (utile pour le SEO), vous pouvez utiliser un routeur côté client aux côtés des helpers `localeMap` / `localeFlatMap` d'Intlayer, et le plugin Vite `intlayerProxy` pour la détection de la langue côté serveur.
+
+Tout d'abord, ajoutez `intlayerProxy` à votre configuration Vite :
+
+> Notez que pour utiliser `intlayerProxy` en production, vous devez déplacer `vite-intlayer` de `devDependencies` vers `dependencies`.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayerProxy(), // should be placed first
+    intlayer(),
+  ],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayerProxy(), // should be placed first
+    intlayer(),
+  ],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { intlayer, intlayerProxy } = require("vite-intlayer");
+
+module.exports = defineConfig({
+  plugins: [
+    intlayerProxy(), // should be placed first
+    intlayer(),
+  ],
+});
+```
+
+### (Optionnel) Étape 10 : Changer l'URL lorsque la langue change
+
+Pour mettre à jour l'URL du navigateur lorsque la langue change, utilisez `useRewriteURL` aux côtés du sélecteur de langue :
+
+```typescript fileName="src/locale-switcher.ts" codeFormat="typescript"
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { getLocaleName, getLocalizedUrl } from "intlayer";
+import { useLocale, useRewriteURL } from "lit-intlayer";
+
+@customElement("locale-switcher")
+export class LocaleSwitcher extends LitElement {
+  private locale = useLocale(this);
+
+  // Réécrit automatiquement l'URL actuelle lorsque la langue change.
+  private _rewriteURL = useRewriteURL(this);
+
+  private _onChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    this.locale.setLocale(select.value as any);
+  }
+
+  override render() {
+    return html`
+      <select @change=${this._onChange}>
+        ${this.locale.availableLocales.map(
+          (loc) => html`
+            <option value=${loc} ?selected=${loc === this.locale.locale}>
+              ${getLocaleName(loc)}
+            </option>
+          `
+        )}
+      </select>
+    `;
+  }
+}
+```
+
+### (Optionnel) Étape 11 : Changer les attributs de langue et de direction HTML
+
+Mettez à jour les attributs `lang` et `dir` de la balise `<html>` pour qu'ils correspondent à la langue actuelle pour l'accessibilité et le SEO.
+
+```typescript fileName="src/my-element.ts" codeFormat="typescript"
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { getHTMLTextDir } from "intlayer";
+import { useLocale } from "lit-intlayer";
+
+@customElement("my-element")
+export class MyElement extends LitElement {
+  private locale = useLocale(this, {
+    onLocaleChange: (loc) => {
+      document.documentElement.lang = loc;
+      document.documentElement.dir = getHTMLTextDir(loc);
+    },
+  });
+
+  override render() {
+    return html`<!-- votre contenu -->`;
+  }
+}
+```
+
+### (Optionnel) Étape 12 : Extraire le contenu de vos composants
+
+Si vous avez une base de code existante, transformer des milliers de fichiers peut prendre du temps.
+
+Pour faciliter ce processus, Intlayer propose un [compilateur](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/compiler.md) / [extracteur](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/cli/extract.md) pour transformer vos composants et extraire le contenu.
+
+Pour le configurer, vous pouvez ajouter une section `compiler` dans votre fichier `intlayer.config.ts` :
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Reste de votre config
+  compiler: {
+    /**
+     * Indique si le compilateur doit être activé.
+     */
+    enabled: true,
+
+    /**
+     * Définit le chemin des fichiers de sortie
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * Indique si les composants doivent être sauvegardés après avoir été transformés.
+     * De cette façon, le compilateur peut être exécuté une seule fois pour transformer l'application, puis il peut être supprimé.
+     */
+    saveComponents: false,
+
+    /**
+     * Préfixe de clé de dictionnaire
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+### Configurer TypeScript
+
+Assurez-vous que votre configuration TypeScript inclut les types autogénérés.
+
+```json5 fileName="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+  },
+  "include": ["src", ".intlayer/**/*.ts"],
+}
+```
+
+> `experimentalDecorators` et `useDefineForClassFields: false` sont requis par Lit pour le support des décorateurs.
+
+### Configuration Git
+
+Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les commettre dans votre dépôt Git.
+
+Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier `.gitignore` :
+
+```bash
+# Ignorez les fichiers générés par Intlayer
+.intlayer
+```
+
+### Extension VS Code
+
+Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l'**extension officielle Intlayer VS Code**.
+
+[Installer depuis le VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+Cette extension fournit :
+
+- **L'autocomplétion** pour les clés de traduction.
+- **La détection d'erreurs en temps réel** pour les traductions manquantes.
+- **Des aperçus en ligne** du contenu traduit.
+- **Des actions rapides** pour créer et mettre à jour facilement les traductions.
+
+Pour plus de détails sur l'utilisation de l'extension, reportez-vous à la [documentation de l'extension Intlayer VS Code](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Aller plus loin
+
+Pour aller plus loin, vous pouvez implémenter l'[éditeur visuel](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_visual_editor.md) ou externaliser votre contenu en utilisant le [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/fr/intlayer_CMS.md).