Traduisez votre site Vite et Svelte avec Intlayer | Internationalisation (i18n)

Table des matières

Pourquoi Intlayer plutôt que des alternatives ?

Par rapport aux solutions principales telles que svelte-i18n ou i18next, 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 Svelte

Voir le Modèle d'application sur GitHub.

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 svelte-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     Le package 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.

   • svelte-intlayer Le package qui intègre Intlayer avec une application Svelte. Il fournit des context providers et des hooks pour l'internationalisation dans Svelte.

   • vite-intlayer Inclut le plugin Vite pour intégrer Intlayer avec le bundler Vite, ainsi qu'un middleware pour détecter la locale préférée de l'utilisateur, gérer les cookies, et gérer la redirection des 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 locales
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Grâce à ce fichier de configuration, vous pouvez configurer les URL localisées, la redirection via 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, consultez 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 { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [svelte(), intlayer()],
   });
   

   Le plugin Vite intlayer() est utilisé pour intégrer Intlayer avec Vite. Il assure la génération des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer au sein de l'application Vite. De plus, il fournit des alias pour optimiser les performances.

4. 4

   Déclarez votre contenu

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

   src/app.content.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
     },
   } 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). Et correspondent à l'extension de 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, consultez la documentation sur la déclaration de contenu.

5. 5

   Utiliser Intlayer dans votre code

   src/App.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script>
     import { useIntlayer } from "svelte-intlayer";
   
     const content = useIntlayer("app");
   </script>
   
   <div>
   
   
   <!-- Afficher le contenu comme contenu simple -->
   <h1>{$content.title}</h1>
   <!-- Pour afficher le contenu éditable via l'éditeur -->
   <h1>{@const Title = $content.title}<Title /></h1>
   <!-- Pour afficher le contenu en tant que chaîne de caractères -->
   <div aria-label={$content.title.value}></div>
   <div aria-label={$content.title.toString()}></div>
   <div aria-label={String($content.title)}></div>
   

   Si votre application existe déjà, vous pouvez utiliser le Compilateur Intlayer, ainsi que la commande d'extraction, pour transformer des milliers de composants en une seconde.

6. 6

   Changer la langue de votre contenu

   Facultatif

   src/App.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script lang="ts">
   import  { getLocaleName } from 'intlayer';
   import { useLocale } from "svelte-intlayer";
   
   // Obtenir les informations de locale et la fonction setLocale
   const { locale, availableLocales, setLocale } = useLocale();
   
   // Gérer le changement de locale
   const changeLocale = (event: Event) => {
     const target = event.target as HTMLSelectElement;
     const newLocale = target.value;
     setLocale(newLocale);
   };
   </script>
   
   <div>
     <select value={$locale} on:change={changeLocale}>
       {#each availableLocales ?? [] as loc}
         <option value={loc}>
           {getLocaleName(loc)}
         </option>
       {/each}
     </select>
   </div>
   

7. 7

   Rendre du Markdown

   Facultatif

   Intlayer prend en charge le rendu du contenu Markdown directement dans votre application Svelte. Par défaut, le Markdown est traité comme du texte brut. Pour convertir le Markdown en HTML enrichi, vous pouvez intégrer @humanspeak/svelte-markdown ou un autre parseur Markdown.

   Pour voir comment déclarer du contenu markdown en utilisant le package intlayer, consultez la documentation markdown.

   src/App.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script>
     import { setIntlayerMarkdown } from "svelte-intlayer";
   
     setIntlayerMarkdown((markdown) =>
      // rendre le contenu markdown sous forme de chaîne
      return markdown;
     );
   </script>
   
   <h1>{$content.markdownContent}</h1>
   

   Vous pouvez également accéder aux données front-matter de votre markdown en utilisant la propriété content.markdownContent.metadata.xxx.

8. 8

   Configurer l’éditeur / CMS intlayer

   Facultatif

   Pour configurer l’éditeur intlayer, vous devez suivre la documentation de l’éditeur intlayer.

   Pour configurer le CMS intlayer, vous devez suivre la documentation du CMS intlayer.

9. 7

   Ajouter le routage localisé à votre application

   Facultatif

   Pour gérer le routage localisé dans votre application Svelte, vous pouvez utiliser svelte-spa-router avec localeFlatMap d'Intlayer pour générer les routes pour chaque locale.

   Tout d'abord, installez svelte-spa-router :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install svelte-spa-router
   npx intlayer init
   

   Ensuite, créez un fichier Router.svelte pour définir vos routes :

   src/Router.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script lang="ts">
   import { localeFlatMap } from "intlayer";
   import Router from "svelte-spa-router";
   import { wrap } from "svelte-spa-router/wrap";
   import App from "./App.svelte";
   
   const routes = Object.fromEntries(
       localeFlatMap(({locale, urlPrefix}) => [
       [
           urlPrefix || '/',
           wrap({
               component: App,
               props: {
                   locale,
               },
           }),
       ],
       ])
   );
   </script>
   
   <Router {routes} />
   

   Mettez à jour votre main.ts pour monter le composant Router au lieu de App :

   src/main.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { mount } from "svelte";
   import Router from "./Router.svelte";
   
   const app = mount(Router, {
     target: document.getElementById("app")!,
   });
   
   export default app;
   

   Enfin, mettez à jour votre App.svelte pour recevoir la propriété locale et l'utiliser avec useIntlayer :

   src/App.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script lang="ts">
   import type { Locale } from 'intlayer';
   import { useIntlayer } from "svelte-intlayer";
   import Counter from './lib/Counter.svelte';
   import LocaleSwitcher from './lib/LocaleSwitcher.svelte';
   
   export let locale: Locale;
   
   $: content = useIntlayer('app', locale);
   </script>
   
   <main>
     <div class="locale-switcher-container">
       <LocaleSwitcher currentLocale={locale} />
     </div>
   
     <!-- ... reste de votre application ... -->
   </main>
   

   Configurer le routage côté serveur (optionnel)

   En parallèle, vous pouvez également utiliser le intlayerProxy pour ajouter un routage côté serveur à votre application. Ce plugin détectera automatiquement la locale actuelle en fonction de l'URL et définira le cookie de locale approprié. Si aucune locale n'est spécifiée, le plugin déterminera la locale la plus appropriée en fonction des préférences linguistiques du navigateur de l'utilisateur. Si aucune locale n'est détectée, il redirigera vers la locale par défaut.

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

   Depuis Intlayer v9, intlayerProxy() est directement intégré au plugin intlayer() et activé par défaut via l'option routing.enableProxy (true par défaut). Son enregistrement séparé comme indiqué ci-dessous est désormais 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é. Voir 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 { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       svelte(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 8

    Modifier l'URL lorsque la locale change

    Facultatif

    Pour permettre aux utilisateurs de changer de langue et de mettre à jour l'URL en conséquence, vous pouvez créer un composant LocaleSwitcher. Ce composant utilisera getLocalizedUrl de intlayer et push de svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // Obtenir les informations de la locale
    const { locale, availableLocales } = useLocale();
    
    // Gérer le changement de locale
    const changeLocale = (event: Event) => {
      plugins: [intlayerProxy(), // should be placed first
     svelte(), intlayer()],
    });
    

11. 8

    Modifier l’URL lors du changement de langue

    Facultatif

    Pour permettre aux utilisateurs de changer de langue et de mettre à jour l’URL en conséquence, vous pouvez créer un composant LocaleSwitcher. Ce composant utilisera getLocalizedUrl de intlayer et push de svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // Récupérer les informations de la locale
    const { locale, availableLocales } = useLocale();
    
    // Gérer le changement de langue
    const changeLocale = (event: Event) => {
      const target = event.target as HTMLSelectElement;
      const newLocale = target.value;
      const currentUrl = window.location.pathname;
      const url = getLocalizedUrl(currentUrl, newLocale);
      push(url);
    };
    </script>
    
    <div class="locale-switcher">
      <select value={currentLocale ?? $locale} onchange={changeLocale}>
        {#each availableLocales ?? [] as loc}
          <option value={loc}>
            {getLocaleName(loc)}
          </option>
        {/each}
      </select>
    </div>
    

12. 9

    Extraire le contenu de vos composants

    Facultatif

    Si vous avez une base de code existante, transformer des milliers de fichiers peut prendre beaucoup de 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 configuration
      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 dCompilateur 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 fichier 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.

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 dans votre fichier .gitignore :

#  Ignorer 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 Extension.

Installer depuis le VS Code Marketplace

Cette extension offre :

• Autocomplétion pour les clés de traduction.
• Détection d’erreurs en temps réel pour les traductions manquantes.
• Aperçus en ligne du contenu traduit.
• Actions rapides pour créer et mettre à jour facilement les traductions.

Pour plus de détails sur l’utilisation de l’extension, consultez 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