Traduire votre site Astro 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

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

   npm install intlayer astro-intlayer# Optionnel : Ajoutez le support pour les îles Reactnpm install react react-dom react-intlayer @astrojs/react

   • 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.

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 à votre configuration Astro.

   astro.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport 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}).

   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.

   src/pages/index.astro

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  defaultLocale,  localeMap,  getHTMLTextDir,  type LocalesValues,} from "intlayer";import LocaleSwitcher from "../components/LocaleSwitcher.astro";// Get the current locale from the URL (e.g. /es/about -> 'es')const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;// Get the content for the 'app' dictionaryconst { 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>    <!-- 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>

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

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

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

   • Intlayer + React : Intlayer avec React
   • Intlayer + Vue : Intlayer avec Vue
   • Intlayer + Svelte : Intlayer avec Svelte
   • Intlayer + Solid : Intlayer avec Solid
   • Intlayer + Preact : Intlayer avec Preact
8. 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

   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(), // Ajoute le plugin du compilateur ],});

   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.