Die Astro-Integration installieren

Die Installation dauert vier Schritte: Paket hinzufügen, API-Schlüssel in .env einfügen, Integration in astro.config.mjs registrieren und eine Komponente zum Layout hinzufügen. Danach wird jede bereits vorhandene Seite auch unter dem Präfix jeder Sprache bereitgestellt, z. B. /fr/about.

Bevor Sie beginnen

• Astro 5 oder neuer, mit output: 'server' oder output: 'static'. Server-Rendering benötigt außerdem einen Astro-Adapter.
• Node 18 oder neuer. Das Lesen von .env und .env.local erfordert Node 20.12 oder neuer. Auf älteren Node-Versionen werden die Dateien ohne Fehler übersprungen. Setzen Sie stattdessen UNIVERSALLY_API_KEY in der Prozessumgebung.
• Die Rolle „Owner“ oder „Admin“ im Workspace, um das Projekt zu erstellen und dessen API-Schlüssel anzuzeigen. Editoren sehen stattdessen „Bitten Sie einen Projektadministrator um den API-Schlüssel dieses Projekts“.

Projekt erstellen

1. Starten Sie ein neues Projekt. Wählen Sie unter Wählen Sie Ihre Technologie Astro (gekennzeichnet als Beta).
2. Geben Sie die Domain ein, die vollqualifizierte Domain, unter der die Website bereitgestellt wird. Sie ist für Astro erforderlich.
3. Geben Sie Projektname ein, überprüfen Sie Quellsprache (standardmäßig Englisch (US)) und klicken Sie auf Weiter.
4. Wählen Sie unter Einrichtungshinweise SDK unter Wie sollen übersetzte Seiten bereitgestellt werden? und klicken Sie auf Weiter.

Der Bildschirm listet dann die vier Installationsschritte unten auf, mit einem Zähler „{n} von 4 erledigt“. Jeder Schritt hat eine Schaltfläche Als erledigt markieren. Die Häkchen werden nur in Ihrem Browser gespeichert und blockieren nichts. Dieselben Schritte bleiben später unter Einrichtung in der Projektseitenleiste verfügbar.

1. Integration installieren

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

2. API-Schlüssel hinzufügen

Fügen Sie die Zeile von der Einrichtungsseite in .env neben Ihren anderen Geheimnissen im Astro-Projektstammverzeichnis ein:

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

Der Schlüssel ist eine Zeichenkette mit 64 Zeichen. Bewahren Sie ihn auf dem Server auf und committen Sie niemals .env. Derselbe Schlüssel befindet sich unter API-Einstellungen hinter API-Schlüssel anzeigen. Siehe API-Schlüssel finden.

3. Astro konfigurieren

Registrieren Sie die Integration in astro.config.mjs und setzen Sie site auf Ihre Domain:

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() liest den Schlüssel aus .env, daher übergeben Sie ihm nichts. site ist für hreflang-Links erforderlich, da es sich um absolute URLs handeln muss. Eine statische Website verzichtet auf den Adapter und verwendet output: 'static'. Jede Option ist in Astro-Integrationsoptionen aufgeführt.

Um Astro.locals zu typisieren, fügen Sie zwei Zeilen zu src/env.d.ts hinzu:

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

4. In Ihren Seiten verwenden

Fügen Sie das Head-Tag einmal in Ihr Layout ein und übersetzen Sie dann Zeichenketten mit t(). Dies ist 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 /> hat keine Props. Es rendert die hreflang-Links und das Skript für den Sprachumschalter. Wickeln Sie dann den Text einer Seite ein, hier 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>

Eine Seitendatei dient jeder Sprache. Seiten in Astro übersetzen deckt t(), href(), Inline-HTML und Inseln ab.

Sprachen hinzufügen

1. Klicken Sie auf Weiter zu Sprachen.
2. Fügen Sie unter Sprachen hinzufügen mindestens eine Zielsprache hinzu. Ihr URL-Format bestimmt das Präfix: Sprachcode (Standard) ergibt /fr/, Regionencode verwendet die Region, sodass Spanisch (Mexiko) zu /mx/ wird, und Benutzerdefiniert verwendet zwei bis sechs Zeichen. Siehe Sprachen hinzufügen.
3. Klicken Sie auf Fertig stellen. Diese Schaltfläche bleibt deaktiviert, bis das Projekt eine Sprache hat.

Sprachen werden gelesen, wenn Ihre Astro-Konfiguration ausgeführt wird. Starten Sie den Entwicklungsserver nach dem Hinzufügen neu.

Überprüfen Sie, ob es funktioniert hat

npx astro dev

Öffnen Sie http://localhost:4321/about für Ihren Quelltext und http://localhost:4321/fr/about für Französisch. Das erste Rendern einer neuen Zeichenfolge zeigt den Quelltext. Laden Sie nach ein oder zwei Sekunden neu, und sie ist übersetzt. Zeigen Sie den Seitenquelltext an, um ein <link rel="alternate" hreflang> pro Sprache zu bestätigen.

Wenn es nicht funktioniert

• Der Build schlägt mit "set UNIVERSALLY_API_KEY in .env…" fehl: Der Schlüssel ist nicht in den Optionen, der Umgebung, .env.local oder .env neben astro.config.mjs.
• /fr/about gibt 404 zurück: Die Sprache wurde nach dem Start des Entwicklungsservers hinzugefügt, oder ihr Live-Schalter ist ausgeschaltet. Starten Sie neu.
• Keine hreflang-Links: site fehlt in astro.config.mjs.

Weitere Fälle finden Sie unter Fehlerbehebung bei Astro-Integrationen.