Installa l'integrazione Astro

L'installazione richiede quattro passaggi: aggiungi il pacchetto, inserisci la tua chiave API in .env, registra l'integrazione in astro.config.mjs e aggiungi un componente al tuo layout. Dopodiché, ogni pagina che già possiedi viene servita anche sotto il prefisso di ogni lingua, come /fr/about.

Prima di iniziare

• Astro 5 o versioni successive, con output: 'server' o output: 'static'. Il rendering lato server richiede anche un adattatore Astro.
• Node 18 o versioni successive. La lettura di .env e .env.local richiede Node 20.12 o versioni successive. Su versioni precedenti di Node i file vengono saltati senza errori, quindi imposta UNIVERSALLY_API_KEY nell'ambiente di processo.
• Ruolo Proprietario o Amministratore nell'area di lavoro, per creare il progetto e visualizzare la sua chiave API. Gli editor vedranno "Chiedi a un amministratore del progetto la chiave API di questo progetto." invece della chiave.

Crea il progetto

1. Avvia un nuovo progetto. Sotto Seleziona la tua tecnologia, scegli Astro (contrassegnato come Beta).
2. Compila Dominio, il dominio completo in cui il sito viene servito. È obbligatorio per Astro.
3. Compila Nome progetto, controlla Lingua di origine (Inglese (US) per impostazione predefinita) e fai clic su Avanti.
4. Su Istruzioni di configurazione, scegli SDK sotto Come devono essere servite le pagine tradotte? e fai clic su Continua.

La schermata elenca quindi i quattro passaggi di installazione sottostanti, con un contatore "{n} di 4 completati". Ogni passaggio ha un pulsante Segna come completato. Le spunte sono memorizzate solo nel tuo browser e non bloccano nulla. Gli stessi passaggi rimangono disponibili in seguito sotto Configurazione nella barra laterale del progetto.

1. Installa l'integrazione

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

2. Aggiungi la tua chiave API

Inserisci la riga dalla pagina di configurazione in .env, accanto ai tuoi altri segreti, nella root del progetto Astro:

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

La chiave è una stringa di 64 caratteri. Conservala sul server e non inviare mai .env. La stessa chiave si trova in Impostazioni API dietro Mostra chiave API. Vedi Trova la tua chiave API.

3. Configura Astro

Registra l'integrazione in astro.config.mjs e imposta site sul tuo dominio:

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() legge la chiave da .env, quindi non le passi nulla. site è obbligatorio per i link hreflang, poiché devono essere URL assoluti. Un sito statico omette l'adattatore e utilizza output: 'static'. Ogni opzione è elencata in Opzioni di integrazione Astro.

Per digitare Astro.locals, aggiungi due righe a src/env.d.ts:

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

4. Usalo nelle tue pagine

Aggiungi il tag head una volta nel tuo layout, quindi traduci le stringhe con t(). Questo è 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 /> non accetta props. Renderizza i link hreflang e lo script dello switcher di lingua. Quindi racchiudi il testo di una pagina, qui 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 file di una pagina serve ogni lingua. Traduci pagine in Astro copre t(), href(), HTML inline e isole.

Aggiungi lingue

1. Fai clic su Continua alle lingue.
2. Su Aggiungi lingue, aggiungi almeno una lingua di destinazione. Il suo Formato URL decide il prefisso: Codice lingua (l'impostazione predefinita) fornisce /fr/, Codice regione utilizza la regione, quindi Spagnolo (Messico) diventa /mx/ e Personalizzato richiede da 2 a 6 caratteri. Vedi Aggiungi lingue.
3. Fai clic su Fine. Rimane disabilitato finché il progetto non ha una lingua.

Le lingue vengono lette all'esecuzione della configurazione di Astro. Riavvia il server di sviluppo dopo averne aggiunta una.

Verifica che abbia funzionato

npx astro dev

Apri http://localhost:4321/about per il tuo testo sorgente e http://localhost:4321/fr/about per il francese. Il primo rendering di una nuova stringa mostra il testo sorgente. Ricarica dopo uno o due secondi e verrà tradotta. Visualizza l'origine della pagina per confermare un <link rel="alternate" hreflang> per lingua.

Se non funziona

• La build fallisce con "set UNIVERSALLY_API_KEY in .env…": la chiave non è nelle opzioni, nell'ambiente, in .env.local o in .env accanto a astro.config.mjs.
• /fr/about restituisce 404: la lingua è stata aggiunta dopo l'avvio del server di sviluppo o il suo interruttore Live è disattivato. Riavvia.
• Nessun link hreflang: site manca da astro.config.mjs.

Altri casi sono in Risoluzione dei problemi di integrazione di Astro.