Traduire votre site Astro avec Intlayer

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

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
   

   le flag --interactive est optionnel. 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
   

   • 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, un middleware qui résout la locale de chaque requête dans Astro.locals.intlayer, ainsi que les hooks useIntlayer / useDictionary / useLocale. Le même chemin d'importation résout vers l'implémentation serveur dans votre frontmatter .astro et vers l'implémentation client (basée sur vanilla-intlayer) dans les blocs <script>.

2. 2

   Configurer votre projet

   Architecture

   Dans cette architecture, l'intégration intlayer() enregistrée dans astro.config.ts compile vos dictionnaires et ajoute un middleware qui résout la locale de chaque requête et l'expose sur Astro.locals.intlayer. Les pages résident sous un segment rest src/pages/[...locale]/, ainsi la locale par défaut est servie sans préfixe et chaque autre locale dispose de sa propre URL dédiée. Les fichiers .astro lisent le contenu avec les hooks useIntlayer / useLocale d'astro-intlayer, et les déclarations de contenu sont placées aux côtés de vos composants dans src/.

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Configuration

   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.

   documentation de configuration
3. 3

   Intégrer Intlayer dans votre configuration Astro

   Ajoutez le plugin intlayer à 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 { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer()],
   });
   

   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.

4. 4

   Déclarer votre contenu

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

   src/app.content.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   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.

   documentation de déclaration de contenu
5. 5

   Utiliser le contenu dans Astro

   Consommez vos dictionnaires dans les fichiers .astro avec les hooks exportés par astro-intlayer. Ils partagent les signatures de react-intlayer : useIntlayer("key") renvoie le contenu d'un dictionnaire et useLocale() la locale actuelle, sans aucun argument à transmettre.

   La locale provient du middleware astro-intlayer, que l'intégration enregistre pour vous en amont de votre propre src/middleware.ts. Il la résout pour chaque requête, à partir du préfixe d'URL, puis de la locale persistée par le client (cookie ou en-tête), puis de Accept-Language, et la stocke dans Astro.locals.intlayer. Les pages pré-rendues utilisent uniquement l'URL, car elles sont générées une seule fois pour chaque visiteur.

   Vous devez également ajouter des métadonnées SEO telles que les liens hreflang et canoniques à chaque page et inclure un sélecteur de langue pour permettre aux utilisateurs de changer de langue.

   src/pages/index.astro

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // Locale résolue par le middleware (ex. /es/about -> 'es')
   const { locale } = useLocale();
   
   // Contenu du dictionnaire 'app' pour cette locale
   const { title } = useIntlayer("app");
   ---
   
   <!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>
   
       <!-- Canonical link: Tells search engines which is the primary version of this page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Tell Google about all localized versions -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback for users in unmatched languages -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <header>
         <LocaleSwitcher />
       </header>
       <main>
         <h1>{title}</h1>
       </main>
     </body>
   </html>
   

   Astro.locals.intlayer expose également locale, defaultLocale et availableLocales à vos propres middlewares et points de terminaison. Passez une locale ou un sélecteur en second argument (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })) pour surcharger la locale de la requête pour un appel.

6. 6

   Routage localisé

   Créez des segments de route dynamiques pour servir des pages localisées (par exemple, src/pages/[locale]/index.astro) :

   src/pages/[locale]/index.astro

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <!-- astro -->
   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   L'intégration Astro ajoute un middleware Vite qui aide au routage sensible à la langue et aux définitions d'environnement pendant le développement. Vous pouvez également créer des liens entre les langues en utilisant votre propre logique ou des utilitaires comme getLocalizedUrl de intlayer.

7. 7

   Ajouter un sélecteur de langue

   Pour permettre aux utilisateurs de basculer entre les langues, vous pouvez créer un composant LocaleSwitcher. Ce composant doit afficher une liste de toutes les locales prises en charge et lier vers la même page dans chaque langue.

   src/components/LocaleSwitcher.astro

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // Dans le navigateur, le même import résout vers l'implémentation client
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Persiste le choix dans le cookie de locale, puis navigue vers l'URL localisée
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   Note sur la persistance : setLocale issu de useLocale côté client enregistre la préférence de langue de l'utilisateur dans un cookie. Cela permet à Intlayer de mémoriser le choix et de rediriger automatiquement l'utilisateur vers sa langue préférée lors de ses visites ultérieures : les pages rendues à la demande (un adaptateur avec output: 'server' ou prerender = false) sont redirigées par le middleware Intlayer avant l'envoi du moindre HTML, tandis que les pages pré-rendues, servies sous forme de fichiers statiques, sont redirigées par un petit script injecté par l'intégration dans chaque page. Définissez routing.enableProxy sur false pour désactiver les deux. Dans astro dev, le cookie est ignoré comme source de redirection à moins que routing.enableProxy ne soit défini sur true, évitant ainsi qu'un cookie obsolète ne détourne les pages sur lesquelles vous travaillez.

   Interopérabilité serveur / client : astro-intlayer résout vers ses hooks serveur dans le frontmatter (en lisant Astro.locals) et vers les hooks client de vanilla-intlayer dans les blocs <script> et les îles (islands), avec les mêmes noms et structures de contenu. setLocale et onChange n'agissent que sur le client, appelez installIntlayer() une fois pour initialiser le store client. astro-intlayer/client expose l'entrée client explicitement.

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 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     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. 9

   Continuer l'utilisation de vos frameworks préférés

   Continuez à construire votre application en utilisant vos frameworks préférés.

   Intlayer avec React

   Intlayer avec Vue

   Intlayer avec Svelte

   Intlayer avec Solid

   Intlayer avec Preact

   Intlayer avec Lit
10. 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.

    compilateur

    extracteur

    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 d'extractionCompilateur 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
    

    Buildez votre application pour transformer vos composants et extraire le contenu

    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.

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