Traduisez votre site web Vite et Vanilla JS en utilisant Intlayer | Internationalisation (i18n)

Table des matières

Pourquoi Intlayer plutôt que des alternatives ?

Par rapport aux solutions principales telles que i18next ou i18n.js, Intlayer est une solution dotée d'optimisations intégrées telles que :

Guide étape par étape pour configurer Intlayer dans une application Vite et Vanilla JS

1. 1

   Installer les dépendances

   Installez les paquets nécessaires en utilisant npm :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npx intlayer init --interactive
   

   l'indicateur --interactive est facultatif. Utilisez intlayer-cli init si vous êtes un agent IA.

   Cette commande détectera votre environnement et installera les packages requis. Par exemple :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install intlayer vanilla-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer Le paquet principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la déclaration de contenu, la transpilation et les commandes CLI.

   • vanilla-intlayer Le paquet qui intègre Intlayer avec des applications en JavaScript pur / TypeScript. Il fournit un singleton pub/sub (IntlayerClient) et des helpers basés sur des callbacks (useIntlayer, useLocale, etc.) pour que n'importe quelle partie de votre application puisse réagir aux changements de langue sans dépendre d'un framework UI.

   • vite-intlayer Comprend le plugin Vite pour intégrer Intlayer avec le bundler Vite, 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.

2. 2

   Configuration de votre projet

   Créez un fichier de configuration pour configurer les langues de votre application :

   intlayer.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   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;
   

   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.

3. 3

   Intégrer Intlayer dans votre configuration Vite

   Ajoutez le plugin intlayer dans votre configuration.

   vite.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

   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.

4. 4

   Initialiser Intlayer dans votre point d'entrée

   Appelez installIntlayer() avant que tout contenu ne soit rendu afin que le singleton global de langue soit prêt.

   src/main.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { installIntlayer } from "vanilla-intlayer";
   
   // Doit être appelé avant de rendre tout contenu i18n.
   installIntlayer();
   
   // Importez et exécutez vos modules d'application.
   import "./app.js";
   

   Si vous utilisez également des déclarations de contenu md() (Markdown), installez également le moteur de rendu markdown :

   src/main.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./app.js";
   

5. 5

   Déclarer votre contenu

   Créez et gérez vos déclarations de contenu pour stocker les traductions :

   src/app.content.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { insert, t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Vanilla",
   
       viteLogoLabel: t({
         en: "Vite Logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
   
       count: insert(
         t({
           en: "count is {{count}}",
           fr: "le compte est {{count}}",
           es: "el recuento es {{count}}",
         })
       ),
   
       readTheDocs: t({
         en: "Click on the Vite logo to learn more",
         fr: "Cliquez sur le logo Vite pour en savoir plus",
         es: "Haga clic en el logotipo de Vite pour obtenir plus d'informations",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   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). Elles doivent correspondre à l'extension du fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Pour plus de détails, reportez-vous à la documentation sur la déclaration de contenu.

6. 6

   Utiliser Intlayer dans votre JavaScript

   vanilla-intlayer reflète l'API de react-intlayer : useIntlayer(key, locale?) renvoie directement le contenu traduit. Enchaînez .onChange() sur le résultat pour vous abonner aux changements de langue - l'équivalent explicite d'un re-rendu React.

   src/main.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { installIntlayer, useIntlayer } from "vanilla-intlayer";
   
   installIntlayer();
   
   // Obtenir le contenu initial pour la langue actuelle.
   // Enchaîner .onChange() pour être averti chaque fois que la langue change.
   const content = useIntlayer("app").onChange((newContent) => {
     // Re-rendre ou patcher uniquement les nœuds DOM affectés
     document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
       newContent.title
     );
     document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
       String(newContent.readTheDocs);
   });
   
   // Rendu initial
   document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
     content.title
   );
   document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
     String(content.readTheDocs);
   

   Accédez aux valeurs terminales en tant que chaînes en les enveloppant dans String(), qui appelle la méthode toString() du nœud et renvoie le texte traduit.

   Lorsque vous avez besoin de la valeur pour un attribut HTML natif (ex: alt, aria-label), utilisez directement .value :

   typescript

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   img.alt = content.viteLogoLabel.value;
   

7. 7

   Changer la langue de votre contenu

   Facultatif

   Pour changer la langue de votre contenu, utilisez la fonction setLocale exposée par useLocale.

   src/locale-switcher.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { getLocaleName } from "intlayer";
   import { useLocale } from "vanilla-intlayer";
   
   export function setupLocaleSwitcher(container: HTMLElement): () => void {
     const { locale, availableLocales, setLocale, subscribe } = useLocale();
   
     const select = document.createElement("select");
     select.setAttribute("aria-label", "Language");
   
     const render = (currentLocale: string) => {
       select.innerHTML = availableLocales
         .map(
           (loc) =>
             `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
               ${getLocaleName(loc)}
             </option>`
         )
         .join("");
     };
   
     render(locale);
     container.appendChild(select);
   
     select.addEventListener("change", () => setLocale(select.value as any));
   
     // Garder le sélecteur synchronisé lorsque la langue change d'ailleurs
     return subscribe((newLocale) => render(newLocale));
   }
   

8. 8

   Rendre du contenu Markdown et HTML

   Facultatif

   Intlayer prend en charge les déclarations de contenu md() et html(). En vanilla JS, le résultat compilé est inséré en tant que HTML brut via innerHTML.

   Compiler et injecter le HTML :

   src/main.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import {
     compileMarkdown,
     installIntlayerMarkdown,
     useIntlayer,
   } from "vanilla-intlayer";
   
   installIntlayerMarkdown();
   
   const content = useIntlayer("app").onChange((newContent) => {
     const el = document.querySelector<HTMLDivElement>(".edit-note")!;
     el.innerHTML = compileMarkdown(String(newContent.editNote));
   });
   
   document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
     compileMarkdown(String(content.editNote));
   

   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 définissez-la via innerHTML.

   WARNING

   N'utilisez innerHTML qu'avec du contenu de confiance. Si le markdown provient d'une entrée utilisateur, assainissez-le d'abord (ex: avec DOMPurify). Vous pouvez installer un moteur de rendu d'assainissement dynamiquement :

   typescript

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";
   
   await installIntlayerMarkdownDynamic(async () => {
     const DOMPurify = await import("dompurify");
     return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));
   });
   

9. 9

   Ajouter le routage localisé à votre application

   Facultatif

   Pour créer des routes uniques pour chaque langue (utile pour le SEO), vous pouvez utiliser intlayerProxy dans votre config Vite pour la détection de la langue côté serveur.

   Tout d'abord, ajoutez intlayerProxy à votre config Vite :

   Notez que pour utiliser intlayerProxy en production, vous devez déplacer vite-intlayer de devDependencies vers dependencies.

   Depuis Intlayer v9, intlayerProxy() est fourni directement dans le plugin intlayer() et activé par défaut via l'option routing.enableProxy (true par défaut). L'enregistrement séparé comme montré ci-dessous est maintenant optionnel — il est conservé pour la compatibilité rétroactive et pour les configurations qui ont besoin de contrôler l'ordre des plugins. Définissez routing.enableProxy: false pour désactiver cette fonctionnalité. Consultez les notes de version v9.

   vite.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 10

    Changer l'URL lorsque la langue change

    Facultatif

    Pour mettre à jour l'URL du navigateur lorsque la langue change, appelez useRewriteURL() après avoir installé Intlayer :

    src/main.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { installIntlayer, useRewriteURL } from "vanilla-intlayer";
    
    installIntlayer();
    
    // Réécrit l'URL immédiatement et lors de chaque changement de langue ultérieur.
    // Renvoie une fonction de désabonnement pour le nettoyage.
    const stopRewriteURL = useRewriteURL();
    

11. 11

    Changer les attributs de langue et de direction HTML

    Facultatif

    Mettez à jour les attributs lang et dir de la balise <html> pour qu'ils correspondent à la langue actuelle pour l'accessibilité et le SEO.

    src/main.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { getHTMLTextDir } from "intlayer";
    import { installIntlayer, useLocale } from "vanilla-intlayer";
    
    installIntlayer();
    
    useLocale({
      onLocaleChange: (locale) => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      },
    });
    

12. 12

    Chargement différé des dictionnaires par langue

    Facultatif

    Pour les grandes applications, vous pouvez fractionner le dictionnaire de chaque langue dans son propre chunk. Utilisez useDictionaryDynamic aux côtés de l'import() dynamique de Vite :

    src/app.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";
    
    installIntlayer();
    
    const unsubscribe = useDictionaryDynamic(
      {
        en: () => import("../.intlayer/dictionaries/en/app.mjs"),
        fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
        es: () => import("../.intlayer/dictionaries/es/app.mjs"),
      },
      "app"
    ).onChange((content) => {
      document.querySelector("h1")!.textContent = String(content.title);
    });
    

    Le bundle de chaque langue n'est récupéré que lorsque cette langue devient active et le résultat est mis en cache - les basculements ultérieurs vers la même langue sont instantanés.

13. 13

    Extraire le contenu de vos composants

    Facultatif

    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 / extracteur pour transformer vos composants et extraire le contenu.

    Pour le configurer, vous pouvez ajouter une section compiler dans votre fichier intlayer.config.ts :

    intlayer.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    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;
    

    Commande ExtractCompilateur Babel

    Exécutez l'extracteur pour transformer vos composants et extraire le contenu

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Mettez à jour votre vite.config.ts pour inclure le plugin intlayerCompiler :

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npm run build # Ou npm run dev
    

(Facultatif) Sitemap et robots.txt (génération au build)

Intlayer fournit des utilitaires - generateSitemap et getMultilingualUrls - pour produire un sitemap.xml multilingue et un robots.txt prêts pour les crawlers, que vous pouvez écrire automatiquement dans public/. En pratique, exécutez un petit script Node avant Vite (par exemple les hooks npm predev / prebuild) afin que ces fichiers soient présents au build ou au serveur de développement.

Sitemap

Le générateur de sitemap Intlayer tient compte de vos locales et ajoute les métadonnées attendues par les moteurs.

Le sitemap généré prend en charge l’espace de noms xhtml:link (extensions hreflang). Contrairement aux générateurs qui ne listent que des URL brutes, Intlayer relie de façon bidirectionnelle toutes les versions linguistiques d’une même page (par ex. /about, /fr/about ou /about?lang=fr selon votre mode de routage), ce qui aide les crawlers.

Robots.txt

Utilisez getMultilingualUrls pour que les règles Disallow couvrent toutes les variantes localisées des chemins sensibles.

1. Créer generate-seo.mjs à la racine du projet

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

Le paquet intlayer doit être installé pour que le script puisse l’importer. Définissez SITE_URL dans l’environnement pour la production (par ex. en CI).

Préférez generate-seo.mjs pour l’ESM Node. Avec generate-seo.js, assurez-vous que "type": "module" est présent dans package.json, ou activez l’ESM côté Node.

2. Lancer le script avant Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Adaptez les commandes si vous utilisez pnpm ou yarn. Vous pouvez aussi appeler ce script depuis la CI ou une autre étape de votre pipeline.

Configurer TypeScript

Assurez-vous que votre configuration TypeScript inclut les types autogénérés.

{
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

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 :

# 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

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.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu en utilisant le CMS.

Questions fréquentes