Guide Rapide pour Localiser un Site Astro

Vous développez un site web multilingue avec Astro ? Vous devez relever deux défis distincts : organiser vos pages de contenu par langue et traduire les éléments d’interface utilisateur comme les boutons et la navigation. Ce guide vous montre exactement comment configurer la localisation statique et dynamique dans Astro, de la configuration de base aux fonctionnalités prêtes pour la production.

Configuration du Routage i18n d’Astro pour le Contenu Statique

Configuration d’astro.config.mjs pour le Support Multilingue

Commencez par configurer le routage i18n intégré d’Astro dans votre fichier astro.config.mjs. Cela indique à Astro quelles langues vous supportez et comment structurer vos URL :

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // Utilise /en/ pour les URL anglaises
    }
  }
});

Définir prefixDefaultLocale: true garantit que toutes les langues utilisent des modèles d’URL cohérents (/en/about, /es/about), facilitant la gestion des liens et évitant les conflits de routage ultérieurs.

Création d’une Structure de Dossiers Localisée

Organisez vos pages en créant des dossiers spécifiques aux locales dans src/pages/ :

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

Chaque dossier correspond à une locale définie dans votre configuration. Astro génère automatiquement les routes correctes basées sur cette structure.

Gestion de la Localisation Statique et Dynamique dans Astro

Organisation des Collections de Contenu par Locale

Pour les articles de blog, la documentation, ou toute collection de contenu, reproduisez la même structure de locale :

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

Lors de l’interrogation du contenu, filtrez par la locale actuelle :

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

Implémentation de Routes Dynamiques avec des Dossiers [locale]

Au lieu de dupliquer les fichiers de pages pour chaque langue, utilisez des routes dynamiques. Créez un dossier [locale] :

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

Dans vos pages, utilisez getStaticPaths() pour générer des routes pour toutes les locales :

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Gestion des Chaînes UI Dynamiques avec Paraglide

Installation et Configuration de Paraglide pour Astro

Alors qu’Astro gère le routage des pages, vous avez besoin d’une solution pour le texte de l’interface utilisateur. Paraglide offre un excellent support TypeScript et une taille de bundle minimale :

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

Création de Fichiers de Traduction et de Clés de Messages

Stockez vos traductions dans messages/ à la racine de votre projet :

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

Importez et utilisez les traductions dans vos composants :

---
import * as m from '../paraglide/messages.js';
---

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

Construction d’un Sélecteur de Langue et de Navigation

Utilisation de getRelativeLocaleUrl() pour des URL Propres

Astro fournit des fonctions utilitaires pour générer des URL localisées appropriées. Utilisez toujours getRelativeLocaleUrl() au lieu de la concaténation manuelle de chaînes :

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

Créez un composant de sélecteur de langue :

---
import { getRelativeLocaleUrlList } from 'astro:i18n';

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

Éviter les Pièges Courants Comme les Routes à Double Préfixe

Attention à ces erreurs courantes :

1. Doubles préfixes : Lors de l’utilisation de routes dynamiques, nettoyez vos slugs pour éviter des URL comme /en/blog/en/my-post :

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. Chemins de locale codés en dur : Utilisez toujours les utilitaires i18n d’Astro au lieu de la concaténation de chaînes
3. Locale manquante dans les liens : Chaque lien interne nécessite une localisation appropriée

Fonctionnalités Avancées d’i18n Astro

Configuration des Langues de Fallback

Configurez des fallbacks pour le contenu non traduit :

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // Affiche le contenu de fallback sans redirection
    }
  }
});

Configuration du Mapping de Domaines pour la Production

Pour les sites de production avec des domaines séparés par langue :

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es'
    }
  }
});

Cela nécessite un rendu côté serveur avec l’adaptateur @astrojs/node ou @astrojs/vercel.

Conclusion

Localiser un site Astro combine deux approches : le routage i18n intégré pour l’organisation du contenu statique et des bibliothèques externes comme Paraglide pour les chaînes UI dynamiques. Commencez par la structure de dossiers et la configuration de routage, puis ajoutez la gestion des traductions. N’oubliez pas d’utiliser les utilitaires URL d’Astro pour éviter les problèmes de routage courants, et considérez les fallbacks et le mapping de domaines pour les déploiements en production.

FAQ

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.