Installer l'intégration Astro

L'installation prend quatre étapes : ajouter le package, placer votre clé API dans .env, enregistrer l'intégration dans astro.config.mjs et ajouter un composant à votre mise en page. Après cela, chaque page que vous avez déjà est également servie sous le préfixe de chaque langue, comme /fr/about.

Avant de commencer

• Astro 5 ou plus récent, avec output: 'server' ou output: 'static'. Le rendu côté serveur nécessite également un adaptateur Astro.
• Node 18 ou plus récent. La lecture de .env et .env.local nécessite Node 20.12 ou plus récent. Sur les anciennes versions de Node, les fichiers sont ignorés sans erreur, définissez donc UNIVERSALLY_API_KEY dans l'environnement du processus à la place.
• Le rôle Propriétaire ou Administrateur dans l'espace de travail, pour créer le projet et voir sa clé API. Les éditeurs voient "Demander à un administrateur de projet la clé API de ce projet." au lieu de la clé.

Créer le projet

1. Démarrez un nouveau projet. Sous Sélectionnez Votre Technologie, choisissez Astro (marqué Bêta).
2. Remplissez Domaine, le nom de domaine complet où le site est servi. Il est requis pour Astro.
3. Remplissez Nom du projet, vérifiez la Langue source (Anglais (US) par défaut), et cliquez sur Suivant.
4. Sur Instructions d'installation, choisissez SDK sous Comment les pages traduites doivent-elles être servies ? et cliquez sur Continuer.

L'écran liste ensuite les quatre étapes d'installation ci-dessous, avec un compteur "{n} sur 4 terminé". Chaque étape a un bouton Marquer comme terminé. Les coches sont stockées uniquement dans votre navigateur et ne bloquent rien. Les mêmes étapes restent disponibles plus tard sous Configuration dans la barre latérale du projet.

1. Installer l'intégration

npm install @universally-sdk/astro
# or: pnpm add @universally-sdk/astro
# or: yarn add @universally-sdk/astro
# or: bun add @universally-sdk/astro

2. Ajouter votre clé API

Placez la ligne de la page de configuration dans .env, à côté de vos autres secrets, à la racine du projet Astro :

UNIVERSALLY_API_KEY=paste-the-64-character-key-here

La clé est une chaîne de 64 caractères. Gardez-la sur le serveur et ne committez jamais .env. La même clé se trouve dans Paramètres API derrière Afficher la clé API. Voir Trouver votre clé API.

3. Configurer Astro

Enregistrez l'intégration dans astro.config.mjs et définissez site sur votre domaine :

import node from '@astrojs/node';
import universally from '@universally-sdk/astro';
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [universally()]
});

universally() lit la clé depuis .env, vous ne lui passez donc rien. site est requis pour les liens hreflang, car ils doivent être des URL absolues. Un site statique abandonne l'adaptateur et utilise output: 'static'. Toutes les options sont listées dans Options d'intégration Astro.

Pour typer Astro.locals, ajoutez deux lignes à src/env.d.ts :

/// <reference types="astro/client" />
/// <reference types="@universally-sdk/astro/env" />

4. L'utiliser dans vos pages

Ajoutez la balise head une fois dans votre mise en page, puis traduisez les chaînes avec t(). Ceci est src/layouts/Base.astro :

---
import { UniversallyHead } from '@universally-sdk/astro/components';

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

<html lang={Astro.currentLocale}>
  <head>
    <meta charset="utf-8" />
    <title>{t('My site')}</title>
    <UniversallyHead />
  </head>
  <body>
    <slot />
  </body>
</html>

<UniversallyHead /> ne prend aucun prop. Il rend les liens hreflang et le script de sélecteur de langue. Ensuite, encapsulez le texte d'une page, ici src/pages/about.astro :

---
import Base from '../layouts/Base.astro';

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

<Base>
  <h1>{t('About us')}</h1>
  <p><a href={href('/pricing')}>{t('See pricing')}</a></p>
</Base>

Un seul fichier de page sert toutes les langues. Traduire des pages dans Astro couvre t(), href(), le HTML en ligne et les îles.

Ajouter des langues

1. Cliquez sur Continuer vers les langues.
2. Sur Ajouter des langues, ajoutez au moins une langue cible. Son Format d'URL décide du préfixe : Code de langue (par défaut) donne /fr/, Code de région utilise la région, donc l'espagnol (Mexique) devient /mx/, et Personnalisé prend de 2 à 6 caractères. Voir Ajouter des langues.
3. Cliquez sur Terminer. Il reste désactivé jusqu'à ce que le projet ait une langue.

Les langues sont lues lorsque votre configuration Astro s'exécute. Redémarrez le serveur de développement après en avoir ajouté une.

Vérifier que cela a fonctionné

npx astro dev

Ouvrez http://localhost:4321/about pour votre texte source et http://localhost:4321/fr/about pour le français. Le premier rendu d'une nouvelle chaîne affiche le texte source. Rechargez après une seconde ou deux et elle est traduite. Affichez la source de la page pour confirmer un <link rel="alternate" hreflang> par langue.

Si cela ne fonctionne pas

• La compilation échoue avec "set UNIVERSALLY_API_KEY in .env…" : la clé n'est pas dans les options, l'environnement, .env.local, ou .env à côté de astro.config.mjs.
• /fr/about renvoie 404 : la langue a été ajoutée après le démarrage du serveur de développement, ou son commutateur En direct est désactivé. Redémarrez.
• Aucun lien hreflang : site est manquant dans astro.config.mjs.

Plus de cas se trouvent dans Dépannage de l'intégration Astro.