Traduire votre site Astro + Svelte avec Intlayer | Internationalisation (i18n)

Table des matières

Pourquoi Intlayer plutôt que des alternatives ?

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

Guide étape par étape pour configurer Intlayer dans Astro + Svelte

Voir le Modèle d’application sur GitHub.

1. 1

   Installer les dépendances

   Installez les packages nécessaires en utilisant votre gestionnaire de packages préféré :

   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 astro-intlayer svelte svelte-intlayer @astrojs/svelte
   

   • intlayer Le package de base qui fournit des outils d’internationalisation pour la gestion de la configuration, les traductions, la déclaration de contenu, la transpilation et les commandes CLI.

   • astro-intlayer Inclut le plugin d’intégration pour Astro 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 traiter les redirections d’URL.

   • svelte Le package Svelte de base.

   • svelte-intlayer Le package qui intègre Intlayer avec les applications Svelte. Il fournit setupIntlayer, ainsi que les stores useIntlayer et useLocale pour l’internationalisation dans Svelte.

   • @astrojs/svelte L’intégration Astro officielle qui permet d’utiliser des îles (islands) de composants Svelte.

2. 2

   Configurer votre projet

   Créez un fichier de configuration pour définir 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;
   

   Via ce fichier de configuration, vous pouvez configurer les URL localisées, les redirections 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, consultez la documentation de configuration.

3. 3

   Intégrer Intlayer dans votre configuration Astro

   Ajoutez le plugin intlayer et l’intégration Svelte à votre configuration Astro.

   astro.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import svelte from "@astrojs/svelte";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), svelte()],
   });
   

   Le plugin d’intégration intlayer() est utilisé pour intégrer Intlayer avec Astro. 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 au sein de l’application Astro. De plus, il fournit des alias pour optimiser les performances.

   L'intégration svelte() permet d'utiliser des îles de composants Svelte via client:only="svelte".

4. 4

   Déclarer votre contenu

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

   src/app.content.ts

   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, à condition qu’elles soient 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,md,mdx,yaml,yml}).

   Pour plus d’informations, consultez la documentation de déclaration de contenu.

5. 5

   Utiliser le contenu dans Astro

   Vous pouvez consommer les dictionnaires directement dans vos fichiers .astro en utilisant les helpers de base exportés par intlayer. Vous devez également ajouter des métadonnées SEO, telles que hreflang et des liens canoniques, sur chaque page et intégrer une île Svelte pour le contenu interactif côté client.

   src/pages/[...locale]/index.astro

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     getHTMLTextDir,
     getPrefix,
     localeMap,
     defaultLocale,
     type LocalesValues,
   } from "intlayer";
   import SvelteIsland from "../../components/svelte/SvelteIsland.svelte";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   const { title } = getIntlayer("app", locale);
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Lien Canonique : Informe les moteurs de recherche de la version principale de cette page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang : Informe Google de toutes les versions localisées -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default : Option de repli pour les utilisateurs avec des langues non correspondantes -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- L’île Svelte rend tout le contenu interactif, y compris le sélecteur de langue -->
       <SvelteIsland locale={locale} client:only="svelte" />
     </body>
   </html>
   

   Si vous souhaitez utiliser votre contenu dans un attribut de type chaîne, tel que alt, title, href, aria-label, etc., vous pouvez utiliser la valeur de la fonction, comme :

   tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   Note sur la configuration du routage : La structure de répertoire que vous utilisez dépend du paramètre middleware.routing dans votre intlayer.config.ts :

   • prefix-no-default (par défaut) : Conserve la langue par défaut à la racine (pas de préfixe) et préfixe les autres. Utilisez [...locale] pour intercepter tous les cas.
   • prefix-all : Toutes les URL ont un préfixe de langue. Vous pouvez utiliser un [locale] standard si vous n’avez pas besoin de gérer la racine séparément.
   • search-param ou no-prefix : Pas besoin de dossier de locale. La locale est gérée via les paramètres de recherche ou les cookies.

6. 6

   Créer le composant Île Svelte

   Créez un composant île qui enveloppe votre application Svelte. La fonction setupIntlayer doit être appelée avec la locale détectée par le serveur avant d’accéder à tout store.

   src/components/svelte/SvelteIsland.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script lang="ts">
     import { useIntlayer, useLocale, setupIntlayer } from "svelte-intlayer";
     import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
     export let locale: LocalesValues;
   
     setupIntlayer(locale);
   
     const content = useIntlayer("app");
     const { locale: currentLocale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale: LocalesValues) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   </script>
   
   <div>
     <h1>{$content.title}</h1>
     <!-- Le sélecteur de langue est rendu en ligne dans l'île -->
     <div class="locale-switcher">
       <span class="switcher-label">Changer de langue :</span>
       <div class="locale-buttons">
         {#each availableLocales as localeItem}
           <button
             class="locale-btn {localeItem === $currentLocale ? 'active' : ''}"
             disabled={localeItem === $currentLocale}
             on:click={() => setLocale(localeItem)}
           >
             <span class="ls-own-name">{getLocaleName(localeItem)}</span>
             <span class="ls-current-name">{getLocaleName(localeItem, $currentLocale)}</span>
             <span class="ls-code">{localeItem.toUpperCase()}</span>
           </button>
         {/each}
       </div>
     </div>
   </div>
   

   La prop locale est transmise de la page Astro (détection serveur) et utilisée pour initialiser setupIntlayer, ce qui en fait la locale initiale pour tous les stores du composant.

7. 7

   Ajouter un sélecteur de langue

   La fonctionnalité de changement de langue est directement intégrée dans l'île Svelte (voir Étape 6 ci-dessus). Elle utilise le store useLocale de svelte-intlayer et navigue vers l'URL localisée lorsqu'un utilisateur sélectionne une nouvelle langue :

   src/components/svelte/SvelteIsland.svelte

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <script lang="ts">
     import { useLocale } from "svelte-intlayer";
     import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
     // Réutilisation de la même configuration locale/setupIntlayer que dans l'Étape 6 ci-dessus...
   
     const {
       locale: currentLocale,
       availableLocales,
       setLocale,
     } = useLocale({
       onLocaleChange: (newLocale: LocalesValues) => {
         // Naviguer vers l'URL localisée lors du changement de langue
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   </script>
   
   <div class="locale-switcher">
     <span class="switcher-label">Changer de langue :</span>
     <div class="locale-buttons">
       {#each availableLocales as localeItem}
         <button
           class="locale-btn {localeItem === $currentLocale ? 'active' : ''}"
           disabled={localeItem === $currentLocale}
           on:click={() => setLocale(localeItem)}
         >
           <span class="ls-own-name">{getLocaleName(localeItem)}</span>
           <span class="ls-current-name">{getLocaleName(localeItem, $currentLocale)}</span>
           <span class="ls-code">{localeItem.toUpperCase()}</span>
         </button>
       {/each}
     </div>
   </div>
   

   Note sur la persistance : L’utilisation de onLocaleChange pour rediriger via window.location.href garantit que la nouvelle URL de langue est bien visitée, permettant au middleware Intlayer de définir le cookie de langue et de mémoriser la préférence de l’utilisateur pour les visites futures.

8. 8

   Sitemap et Robots.txt

   Intlayer fournit des utilitaires pour créer dynamiquement vos sitemaps localisés et fichiers robots.txt.

   Sitemap

   Intlayer est livré avec un générateur de sitemap intégré pour vous aider à créer facilement un sitemap pour votre application. Il gère les routes localisées et ajoute les métadonnées nécessaires pour les moteurs de recherche.

   Le sitemap généré par Intlayer prend en charge l'espace de noms xhtml:link (Hreflang XML Extensions). Contrairement aux générateurs de sitemap par défaut qui ne répertorient que les URL brutes, Intlayer crée automatiquement les liens bidirectionnels requis entre toutes les versions linguistiques d'une page (par exemple, /about, /about?lang=fr et /about?lang=es). Cela garantit que les moteurs de recherche indexent et servent correctement la bonne version linguistique au bon public.

   Créez src/pages/sitemap.xml.ts pour générer un sitemap incluant toutes vos routes localisées.

   src/pages/sitemap.xml.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   Créez src/pages/robots.txt.ts pour gérer le crawl des moteurs de recherche.

   src/pages/robots.txt.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 15

   Extracter 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
   

Configuration TypeScript

Intlayer utilise l’augmentation de module pour tirer parti de TypeScript et rendre votre codebase plus robuste.

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

{
  // ... Vos configurations TypeScript existantes
  "include": [
    // ... Vos configurations TypeScript existantes
    ".intlayer/**/*.ts", // Inclure les types autogénérés
  ],
}

Configuration Git

Il est recommandé d’ignorer les fichiers générés par Intlayer. Cela vous permet d’éviter de les committer dans votre dépôt Git.

Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :

# Ignorer les fichiers générés par Intlayer
.intlayer

Extension VS Code

Pour améliorer l'expérience de développement avec Intlayer, vous pouvez installer l'extension VS Code Intlayer officielle.

Installer depuis le VS Code Marketplace

Cette extension fournit :

• L'autocomplétion pour vos clés de traduction.
• La détection d’erreurs en temps réel pour les traductions manquantes.
• Un aperçu en ligne du contenu traduit.
• Des actions rapides pour créer et mettre à jour vos traductions facilement.

Pour plus d'informations sur l'utilisation de l'extension, consultez la documentation de l'extension VS Code Intlayer.

Aller plus loin

Vous pouvez également implémenter l’éditeur visuel ou externaliser votre contenu en utilisant un CMS.

Questions fréquentes