Routage d'Internationalisation (i18n)
La fonctionnalité d’internationalisation (i18n) d’Astro vous permet d’adapter votre projet pour une audience internationale. Cette API de routage vous aide à générer, utiliser et vérifier les URL produites par votre site multilingue.
Le routage i18n d’Astro vous permet de proposer du contenu multilingue en prenant en charge la configuration d’une langue par défaut, le calcul des URL relatives des pages et l’acceptation des langues préférées fournies par le navigateur de votre visiteur. Vous pouvez également spécifier des langues de repli pour chacune des langues afin que vos visiteurs puissent toujours être dirigés vers un contenu existant sur votre site.
Logique de routage
Titre de la section Logique de routageAstro utilise un middleware pour mettre en œuvre sa logique de routage. Cette fonction middleware est placée en première position où il attend chaque Response
provenant de tout middleware supplémentaire et des routes de chaque page avant d’exécuter finalement sa propre logique.
Cela signifie que les opérations (par exemple les redirections) de votre propre middleware et de la logique de votre page sont exécutées en premier, vos routes sont restituées, puis le middleware i18n effectue ses propres actions, comme vérifier qu’une URL localisée correspond à une route valide.
Vous pouvez aussi choisir d’ajouter votre propre logique i18n en plus ou à la place du middleware i18n d’Astro, vous donnant encore plus de contrôle sur vos routes tout en ayant toujours accès aux fonctions d’assistance d’astro:i18n
.
Configurer le routage i18n
Titre de la section Configurer le routage i18nUne langue par défaut (defaultLocale
) et une liste de toutes les langues prises en charge (locales
) doivent être spécifiées dans un objet de configuration i18n
. De plus, vous pouvez configurer un comportement de routage et de repli plus spécifique pour correspondre aux URL souhaitées.
Créer des dossiers localisés
Titre de la section Créer des dossiers localisésOrganisez vos dossiers de contenu avec du contenu localisé par langue. Créez des dossiers individuels /[locale]/
n’importe où dans src/pages/
et le routage basé sur les fichiers d’Astro créera vos pages aux chemins d’URL correspondants.
Vos noms de dossier doivent correspondre exactement aux éléments dans locales
. Incluez un dossier localisé pour votre langue par défaut (defaultLocale
) seulement si vous utilisez prefixDefaultLocale: true
dans la configuration pour afficher un chemin d’URL localisé pour votre langue par défaut (par exemple /en/about/
).
Répertoiresrc
Répertoirepages
- about.astro
- index.astro
Répertoirees
- about.astro
- index.astro
Répertoirept-br
- about.astro
- index.astro
Les dossiers localisés n’ont pas besoin d’être à la racine du dossier /pages/
.
Créer des liens
Titre de la section Créer des liensUne fois le routage i18n configuré, vous pouvez désormais calculer des liens vers des pages de votre site à l’aide des fonctions d’assistance telles que getRelativeLocaleURL()
disponible avec le module astro:i18n
. Ces liens générés fourniront toujours la bonne route localisée et peuvent vous aider à utiliser ou à vérifier correctement les URL de votre site.
Vous pouvez également continuer à rédiger les liens manuellement.
routing
Titre de la section routingLe routage intégré d’Astro, basé sur les fichiers, crée automatiquement des chemins d’URL pour vous en fonction de la structure de vos fichiers au sein de src/pages/
.
Lorsque vous configurez le routage i18n, les informations sur cette structure de fichiers (et les chemins d’URL correspondants générés) sont disponibles pour les fonctions d’assistance i18n afin qu’elles puissent générer, utiliser et vérifier les routes de votre projet. Bon nombre de ces options peuvent être utilisées ensemble pour encore plus de personnalisation et de flexibilité par langue.
Vous pouvez même choisir d’implémenter manuellement votre propre logique de routage pour un contrôle encore plus grand.
prefixDefaultLocale
Titre de la section prefixDefaultLocale
Ajouté à la version :
astro@3.5.0
Cette option de routage définit si les URL de votre langue par défaut doivent utiliser ou non un préfixe de langue (par exemple /en/about/
).
Toutes les langues prises en charge qui ne correspondent pas à celle par défaut utiliseront un préfixe localisé (par exemple /fr/
ou /french/
) et les fichiers de contenu doivent être situés dans les dossiers appropriés. Cette option de configuration vous permet de spécifier si votre langue par défaut doit également suivre une structure d’URL localisée.
Ce paramètre détermine également où doivent résider les fichiers de page (e.g. src/pages/about/
ou src/pages/en/about
) pour votre langue par défaut, puisque la structure des fichiers et des URL doivent correspondre pour toutes les langues.
-
"prefixDefaultLocale: false"
(par défaut) : les URL dans votre langue par défaut n’auront pas de préfixe/[locale]/
. Toutes les autres langues en auront un. -
"prefixDefaultLocale: true"
: Toutes les URL, en incluant votre langue par défaut, auront un préfixe/[locale]/
.
prefixDefaultLocale: false
Titre de la section prefixDefaultLocale: falseIl s’agit de la valeur par défaut. Activez cette option lorsque les URL dans votre langue par défaut n’auront pas de préfixe /[locale]/
et que les fichiers de votre langue par défaut résident à la racine de src/pages/
:
Répertoiresrc
Répertoirepages
- about.astro
- index.astro
Répertoirees
- about.astro
- index.astro
Répertoirefr
- about.astro
- index.astro
src/pages/about.astro
produira la routeexample.com/about/
src/pages/fr/about.astro
produira la routeexample.com/fr/about/
prefixDefaultLocale: true
Titre de la section prefixDefaultLocale: trueActivez cette option quand toutes les routes auront un préfixe /locale/
dans leur URL et lorsque tous les fichiers de contenu de page, en incluant ceux de votre votre langue par défaut (defaultLocale
), existent dans un dossier localisé :
Répertoiresrc
Répertoirepages
- index.astro // À noter : ce fichier est toujours nécessaire
Répertoireen
- index.astro
- about.astro
Répertoirees
- about.astro
- index.astro
Répertoirept-br
- about.astro
- index.astro
- Les URL sans préfixe de paramètres régionaux, (par exemple
example.com/about/
) renverront un code d’état 404 (introuvable), sauf si vous spécifiez une stratégie de repli.
redirectToDefaultLocale
Titre de la section redirectToDefaultLocale
Ajouté à la version :
astro@4.2.0
Détermine si l’URL d’accueil (/
) générée par src/pages/index.astro
redirigera ou non vers /<defaultLocale>
.
L’utilisation de prefixDefaultLocale: true
définira également automatiquement redirectToDefaultLocale: true
dans votre objet de configuration routing
. Par défaut, le fichier requis src/pages/index.astro
redirigera automatiquement vers la page d’accueil de votre langue par défaut.
Vous pouvez refuser ce comportement en utilisant redirectToDefaultLocale: false
. Cela vous permet d’avoir une page d’accueil de site qui existe en dehors de la structure de dossiers de paramètres régionaux configurée.
Ajouté à la version :
astro@4.6.0
Quand cette option est activée, Astro désactivera son middleware i18n pour que vous puissiez mettre en œuvre votre propre logique personnalisée. Aucune autre option dans routing
(par exemple prefixDefaultLocale
) ne peut être configurée avec routing: "manual"
.
Vous serez responsable de l’écriture de votre propre logique de routage ou d’exécuter le middleware i18n d’Astro manuellement aux côtés du vôtre.
Astro fournit des fonctions d’assistance pour votre middleware afin que vous puissiez contrôler votre propre routage par défaut, vos exceptions, le comportement de repli, la détection des erreurs, etc. : redirectToDefaultLocale()
, notFound()
, et redirectToFallback()
:
Fonction middleware
Titre de la section Fonction middlewareLa fonction middleware
crée manuellement le middleware i18n d’Astro. Cela vous permet d’étendre le routage i18n d’Astro plutôt que de le remplacer complètement.
Vous pouvez exécuter middleware
avec des options de routage en combinaison avec votre propre middleware, en utilisant l’utilitaire sequence
pour déterminer l’ordre :
domains
Titre de la section domains
Ajouté à la version :
astro@4.9.0
Cette option de routage vous permet de personnaliser vos domaines par langue pour les projets générés par le serveur (server
) à l’aide de l’un des deux adapateurs @astrojs/node
ou @astrojs/vercel
avec un site
configuré.
Ajoutez i18n.domains
pour associer n’importe lequel de vos paramètres régionaux (locales
) pris en charge à des URL personnalisées :
Tous les paramètres régionaux (locales
) non associés suivront votre configuration prefixDefaultLocales
. Cependant, même si la valeur est false
, les fichers de page pour votre langue par défaut (defaultLocale
) doivent également exister à l’intérieur d’un dossier localisé. Pour la configuration ci-dessus, un dossier /en/
est requis.
Avec la configuration ci-dessus :
- Le fichier
/fr/about.astro
créera l’URLhttps://fr.example.com/about
. - Le fichier
/es/about.astro
créera l’URLhttps://example.es/about
. - Le fichier
/ja/about.astro
créera l’URLhttps://example.com/ja/about
. - Le fichier
/en/about.astro
créera l’URLhttps://example.com/about
.
Les URL ci-dessus seront également renvoyées par les fonctions getAbsoluteLocaleUrl()
et getAbsoluteLocaleUrlList()
.
fallback
Titre de la section fallbackLe routage i18n d’Astro vous permet de configurer une stratégie de routage de repli. Lorsqu’une page dans une langue n’existe pas (par exemple une page qui n’est pas encore traduite), au lieu d’afficher une page 404, vous pouvez rediriger un utilisateur d’une langue à une autre en fonction de la langue. Ceci est utile lorsque vous n’avez pas encore de page pour chaque route, mais que vous souhaitez quand même fournir du contenu à vos visiteurs.
Par exemple, la configuration ci-dessous définit es
comme paramètres régionaux de repli pour toutes les routes fr
manquantes. Cela signifie qu’un visiteur consultant example.com/fr/my-page/
sera redirigé et affichera le contenu de example.com/es/my-page/
au lieu d’être redirigé vers une page 404 quand src/pages/fr/my-page.astro
n’existe pas.
Astro garantira qu’une page est construite dans src/pages/fr
pour chaque page qui existe dans src/pages/es/
. Si la page n’existe pas déjà, alors une page avec une redirection vers la route es
correspondante sera créée.
Chemins d’accès aux paramètres régionaux personnalisés
Titre de la section Chemins d’accès aux paramètres régionaux personnalisésEn plus de définir les paramètres régionaux (locales
) pris en charge par votre site sous forme de chaînes de caractères (par exemple « en », « pt-br »), Astro vous permet également d’associer un nombre arbitraire de codes
de langue reconnus par le navigateur à une URL personnalisée path
. Alors que les paramètres régionaux peuvent être des chaînes de caractères de n’importe quel format tant qu’ils correspondent à la structure des dossiers de votre projet, les codes
doivent suivre la syntaxe acceptée par le navigateur.
Passez un objet au tableau locales
avec une clé path
pour définir un préfixe d’URL personnalisé et codes
pour indiquer les langues associées à cette URL. Dans ce cas, le nom de votre dossier /[locale]/
doit correspondre exactement à la valeur de path
et vos URL seront générées en utilisant la valeur path
.
Ceci est utile si vous prenez en charge plusieurs variantes d’une langue (par exemple "fr"
, "fr-BR"
et "fr-CA"
) et que vous souhaitez que toutes ces variantes soient associées à la même URL /fr/
, ou même le personnaliser entièrement (par exemple /french/
):
Lors de l’utilisation des fonctions du module virtuel astro:i18n
pour calculer des chemins d’URL valides en fonction de votre configuration (par exemple getRelativeLocaleUrl()
), utilisez path
comme valeur pour locale
.
Limitations
Titre de la section LimitationsCette fonctionnalité présente certaines restrictions :
- L’option
site
est obligatoire. - L’option
output
doit être définie sur"server"
. - Il ne peut pas y avoir de pages individuelles pré-générées.
- La fonctionnalité de l’adaptateur
functionPerRoute
n’est pas supportée.
Astro s’appuie sur les en-têtes suivants afin de prendre en charge la fonctionnalité :
X-Forwarded-Host
etHost
. Astro utilisera le premier et, s’il n’est pas présent, essaiera le second.X-Forwarded-Proto
etURL#protocol
de la requête du serveur.
Assurez-vous que votre serveur proxy/plateforme d’hébergement est en mesure de fournir ces informations. Ne pas récupérer ces en-têtes entraînera une page 404 (code de statut).
Détection de la langue du navigateur
Titre de la section Détection de la langue du navigateurLe routage i18n d’Astro vous permet d’accéder à deux propriétés de détection de la langue du navigateur dans les pages générées à la demande : Astro.preferredLocale
et Astro.preferredLocaleList
. Toutes les pages, y compris les pages statiques pré-générées, ont accès à Astro.currentLocale
.
Ceux-ci combinent l’en-tête Accept-Language
du navigateur et vos paramètres régionaux locales
(chaînes de caractères ou codes
) pour respecter automatiquement les langues préférées de votre visiteur.
-
Astro.preferredLocale
: Astro peut calculer un paramètre régional préféré pour votre visiteur si les paramètres régionaux préférés de son navigateur sont inclus dans votre tableaulocales
. Cette valeur n’est pas définie si aucune correspondance de ce type n’existe. -
Astro.preferredLocaleList
: Un tableau de tous les paramètres régionaux demandés par le navigateur et pris en charge par votre site web. Cela produit une liste de toutes les langues compatibles entre votre site et votre visiteur. La valeur est[]
si aucune des langues demandées par le navigateur n’est trouvée dans votre tableaulocales
. Si le navigateur ne spécifie aucune langue préférée, cette valeur serai18n.locales
. -
Astro.currentLocale
: Le paramètre régional calculé à partir de l’URL actuelle, en utilisant la syntaxe spécifiée dans votre configurationlocales
. Si l’URL ne contient pas de préfixe/[locale]/
, alors la valeur par défaut serai18n.defaultLocale
.
Afin de réussir à faire correspondre les préférences de vos visiteurs, fournissez vos codes
en utilisant le même modèle que celui utilisé par le navigateur.