Traduire des pages dans Astro

Vous traduisez une page Astro en encapsulant son texte dans t() et ses liens internes dans href(), tous deux lus depuis Astro.locals. Tout s'exécute sur le serveur, et un seul fichier de page sert chaque langue.

Avant de commencer

• L'intégration est installée et <UniversallyHead /> est dans votre mise en page. Voir Installer l'intégration Astro.
• Le projet a au moins une langue cible avec son commutateur Live activé.

Traduire du texte avec t()

1. Lisez t depuis Astro.locals dans le frontmatter de la page.
2. Passez chaque morceau de texte source.

---
const { t } = Astro.locals;
---

<h1>{t('About us')}</h1>
<p>{t('We translate websites.')}</p>

t() prend votre texte source et renvoie le texte pour la langue en cours de rendu. Le texte source est la clé, donc la chaîne dans votre code doit correspondre à la chaîne source dans le tableau de bord, caractère par caractère. Un espace supplémentaire ou une virgule modifiée en fait une chaîne différente.

Une chaîne sans traduction renvoie le texte source, donc une page ne plante jamais pendant qu'une traduction est en cours. La chaîne est enregistrée une fois et signalée après la réponse. Sur les pages de langue source, t() renvoie son argument sans recherche ni rapport.

N'appelez jamais t(''). Le traducteur refuse une chaîne vide, et ce rapport échoue avec une erreur enregistrée.

Localiser les liens avec href()

1. Lisez href depuis Astro.locals.
2. Encapsulez chaque chemin interne.

---
const { t, href } = Astro.locals;
---

<a href={href('/pricing')}>{t('See pricing')}</a>

Sur une page française, /pricing devient /fr/pricing, et la chaîne de requête et le fragment sont conservés. Sur la langue source, le chemin revient inchangé, car la langue source est servie sans préfixe.

href() renvoie également ces éléments inchangés :

• une chaîne vide
• les URL relatives au protocole qui commencent par //
• tout ce qui ne commence pas par / : les liens https: et mailto:, les liens tel:, les #fragment, les ?query, et les chemins relatifs
• un chemin qui porte déjà le préfixe, tel que /fr ou /fr/pricing, donc l'appeler deux fois ne pose pas de problème

Lire la langue actuelle

Astro.locals.lang contient le code de variante de la langue en cours de rendu, en minuscules : fr pour le français (France), es-419 pour l'espagnol (Mexique), et en-us sur une page source en anglais (US). Astro.locals contient lang, t et href, et rien d'autre.

Conservez le HTML intégré dans t()

Les balises <strong> et <em> simples peuvent rester dans la chaîne. Affichez le résultat avec set:html :

---
const { t } = Astro.locals;
---

<p set:html={t('Wrap text in <strong>t()</strong> and keep your <em>markup</em> intact.')} />

Une chaîne qui contient une balise est normalisée avant la traduction : les attributs sur les balises intégrées sont remplacés par des marqueurs, et les éléments img et svg sont vidés. Gardez les chaînes en texte brut, ou en <strong> et <em> sans attributs.

Gardez <a> en dehors de t() :

---
const { t, href } = Astro.locals;
---

<p>{t('Compare every plan.')} <a href={href('/pricing')}>{t('See pricing')}</a></p>

L'URL du lien appartient à une langue, donc href() doit la construire. Une URL dans le texte source rend également la clé différente sur chaque page qui renvoie ailleurs, ce qui divise une traduction en plusieurs.

Passer du texte traduit aux îles

Il n'y a pas de t() côté client. Un composant qui s'hydrate dans le navigateur ne reçoit du texte traduit que sous forme de props du fichier .astro :

---
import Counter from '../components/Counter.tsx';

const { t } = Astro.locals;
---

<Counter client:load label={t('Add one')} />

Traduire un site statique

Avec output: 'static', la traduction se produit pendant la construction :

1. Exécutez la construction. Elle charge chaque langue, rend chaque page une fois, puis envoie chaque chaîne qu'elle n'avait pas en un seul appel.
2. Lisez la fin du journal. Si quelque chose était nouveau, il affiche une ligne comme 12 nouvelles chaînes traduites. Reconstruisez pour les inclure.
3. Exécutez à nouveau la construction. Les nouvelles chaînes sont maintenant dans le HTML.

Un site statique n'a pas de code serveur en cours d'exécution après la construction. Les modifications du tableau de bord ne le rejoignent que lorsque vous reconstruisez et redéployez, comme décrit dans Mises à jour de traduction dans Astro.

Vérifier que cela a fonctionné

Ouvrez une page sous un préfixe cible, tel que /fr/about. Le texte que vous avez enveloppé dans t() apparaît traduit après un rechargement, et les liens construits avec href() pointent vers des chemins /fr/. Le texte que vous n'avez pas enveloppé reste dans votre langue source : rien sur la page n'est traduit à moins qu'il ne passe par t().

Si cela ne fonctionne pas

• Une chaîne reste dans la langue source tandis que le reste se traduit : sa clé ne correspond pas au tableau de bord. Comparez l'argument de t() avec la chaîne source, caractère par caractère.
• Toutes les chaînes restent dans la langue source : vérifiez le journal du serveur pour limite de mots atteinte. Voir Dépannage de l'intégration Astro.