Traduci pagine in Astro

Traduci una pagina Astro racchiudendo il suo testo in t() e i suoi link interni in href(), entrambi letti da Astro.locals. Tutto viene eseguito sul server e un file di pagina serve ogni lingua.

Prima di iniziare

• L'integrazione è installata e <UniversallyHead /> è nel tuo layout. Vedi Installa l'integrazione Astro.
• Il progetto ha almeno una lingua di destinazione con il suo interruttore Live attivato.

Traduci testo con t()

1. Leggi t da Astro.locals nel frontmatter della pagina.
2. Passa ogni pezzo di testo sorgente.

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

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

t() prende il tuo testo sorgente e restituisce il testo per la lingua in fase di rendering. Il testo sorgente è la chiave, quindi la stringa nel tuo codice deve corrispondere alla stringa sorgente nel dashboard carattere per carattere. Uno spazio extra o una virgola cambiata la rendono una stringa diversa.

Una stringa senza traduzione restituisce il testo sorgente, quindi una pagina non si interrompe mai mentre una traduzione è in arrivo. La stringa viene registrata una volta e segnalata dopo la risposta. Nelle pagine in lingua sorgente, t() restituisce il suo argomento senza lookup e senza report.

Non chiamare mai t(''). Il traduttore rifiuta una stringa vuota e quel report fallisce con un errore registrato.

Localizza link con href()

1. Leggi href da Astro.locals.
2. Includi ogni percorso interno.

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

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

Su una pagina francese, /pricing diventa /fr/pricing e la stringa di query e l'hash vengono mantenuti. Nella lingua sorgente il percorso torna invariato, perché la lingua sorgente viene servita senza prefisso.

href() restituisce anche questi invariati:

• una stringa vuota
• URL relativi al protocollo che iniziano con //
• qualsiasi cosa che non inizi con /: link https: e mailto:, link tel:, #fragment, ?query e percorsi relativi
• un percorso che porta già il prefisso, come /fr o /fr/pricing, quindi chiamarlo due volte non fa danno

Leggi la lingua corrente

Astro.locals.lang contiene il codice della variante della lingua in fase di rendering, in minuscolo: fr per francese (Francia), es-419 per spagnolo (Messico) e en-us in una pagina sorgente inglese (USA). Astro.locals contiene lang, t e href, e nient'altro.

Mantieni l'HTML inline all'interno di t()

I tag <strong> e <em> semplici possono rimanere all'interno della stringa. Esegui il risultato con set:html:

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

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

Una stringa che contiene un tag viene normalizzata prima della traduzione: gli attributi sui tag inline vengono sostituiti da marcatori e gli elementi img e svg vengono svuotati. Mantieni le stringhe a testo semplice, o a <strong> e <em> senza attributi.

Mantieni <a> fuori da t():

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

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

L'URL del link appartiene a una lingua, quindi href() deve costruirlo. Un URL nel testo sorgente rende anche la chiave diversa su ogni pagina che collega altrove, il che divide una traduzione in molte.

Passa il testo tradotto alle isole

Non esiste un t() lato client. Un componente che si idrata nel browser riceve testo tradotto solo come props dal file .astro:

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

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

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

Traduci un sito statico

Con output: 'static', la traduzione avviene durante la build:

1. Esegui la build. Carica ogni lingua, renderizza ogni pagina una volta, quindi invia ogni stringa che non aveva in una chiamata.
2. Leggi la fine del log. Se qualcosa era nuovo, stampa una riga come 12 nuove stringhe tradotte. Ricostruisci per includerle.
3. Esegui di nuovo la build. Le nuove stringhe sono ora nell'HTML.

Un sito statico non ha codice server in esecuzione dopo la build. Le modifiche alla dashboard lo raggiungono solo quando ricostruisci e ridistribuisci, come descritto in Aggiornamenti delle traduzioni in Astro.

Verifica che abbia funzionato

Apri una pagina sotto un prefisso di destinazione, come /fr/about. Il testo che hai racchiuso in t() appare tradotto dopo un ricaricamento e i link costruiti con href() puntano ai percorsi /fr/. Il testo che non hai racchiuso rimane nella tua lingua sorgente: nulla nella pagina viene tradotto a meno che non passi attraverso t().

Se non funziona

• Una stringa rimane nella lingua sorgente mentre le altre si traducono: la sua chiave non corrisponde alla dashboard. Confronta l'argomento di t() con la stringa sorgente, carattere per carattere.
• Ogni stringa rimane nella lingua sorgente: controlla il log del server per limite di parole raggiunto. Vedi Risoluzione dei problemi di integrazione di Astro.