In questa pagina
Astro è il framework web static-first per siti content-driven: routing file-based, zero JavaScript per default, "island" per interattività opt-in, una modalità SSR-on-demand per le parti che la richiedono. A partire da v4.0 (fine 2023, stabile in v5+, attuale in v7.x), Astro include il routing i18n integrato: prefissazione delle URL (/en/, /de/), l'helper Astro.currentLocale, rilevamento della lingua del browser e helper per le URL come getRelativeLocaleUrl.
Quello che l'i18n integrato di Astro non fornisce è una funzione di traduzione (t()), pluralizzazione o interpolazione dei messaggi. La ricetta i18n ufficiale di Astro mostra un pattern "build it yourself": importate un file JSON per locale e scrivete un piccolo helper di lookup. Questo copre le stringhe semplici, e si ferma dove iniziano plurali, interpolazione e fallback. i18next colma questa lacuna, al build: gira mentre Astro renderizza le pagine, quindi una build statica continua a non inviare JavaScript al browser. Locize gestisce le traduzioni: locize-cli scarica gli ultimi JSON pubblicati in src/i18n/locales/{lng}/{ns}.json prima della build, e i18next legge quei file.
Questo articolo guida l'integrazione end-to-end. Il codice completo è disponibile su github.com/locize/locize-astro-example.
Aggiornamento (17 novembre 2026): la prima versione di questo articolo usava un helper
t()scritto a mano. Ora usa i18next, che aggiunge plurali, interpolazione (nel formato JSON di i18next che Locize usa per default) e fallback, sempre senza JavaScript nel browser. L'esempio è passato ad Astro 7.
Se invece siete su Nuxt, seguite il walkthrough di Nuxt 4. Se siete su React Router v7 (modalità Framework), vedete il walkthrough di React Router v7. Entrambi coprono integrazioni più ricche (editor in-context, saveMissing a runtime) che non si adattano direttamente al modello static-by-default di Astro.
TL;DR
- Configurate il routing i18n integrato di Astro in
astro.config.mjs: lista delle locale +prefixDefaultLocale: trueper URL uniformi. - Usate rotte di pagina dinamiche
[lang]/congetStaticPathscosì che ogni locale venga pre-renderizzata staticamente. - Sincronizzate le traduzioni nell'app al build tramite il comando
downloaddilocize-cli. Nessun hop CDN a runtime, nessuna considerazione SSR. - Caricate i file scaricati in i18next una sola volta in
src/i18n/index.ts; ogni pagina ottiene unat()per la propria lingua congetFixedT. In una build statica i18next gira solo al build, quindi nessun JavaScript arriva al browser. - Scrivete i tag
<link rel="alternate" hreflang>nel vostro layout: il routing di Astro non li aggiunge. - Fate arrivare le nuove chiavi via
npm run syncLocaleso l'app web di Locize, a seconda di cosa si adatta al vostro workflow. Non è possibile unsaveMissinga runtime dal layer statico. - Vi serve saveMissing a runtime, fetch live tramite CDN o l'editor in-context? Montate una qualsiasi island React/Vue/Svelte via
@astrojs/<framework>e usatei18next-locize-backend+ il pacchettolocizedentro l'island. - Esempio completo funzionante: github.com/locize/locize-astro-example
Come si incastrano i pezzi
Astro è static-by-default. Le pagine vengono pre-renderizzate in HTML al build e servite come file statici (o, in modalità SSR, tramite un adapter on demand). L'i18n integrato di Astro possiede il layer di routing (prefissazione URL, redirect locale-aware, helper di rilevamento del browser) ma resta deliberatamente fuori dal layer di traduzione dei messaggi. Ecco perché ogni tutorial i18n di Astro finisce con "ora scrivete il vostro helper t()". i18next è quel layer, già pronto.
Locize è il livello di gestione delle traduzioni. L'integrazione è solo in bundle a runtime:
- Al build:
locize-cliscarica gli ultimi JSON pubblicati dal CDN di Locize insrc/i18n/locales/{lng}/{ns}.json.src/i18n/index.tscarica in i18next ogni file che trova lì. t()è i18next, chiamata mentre Astro renderizza ogni pagina: plurali, interpolazione, fallback alla lingua di default, un namespace per file. In una build statica niente di tutto questo arriva al browser: l'output è HTML puro.- Gli aggiornamenti richiedono una rebuild, come qualsiasi altra modifica di contenuto Astro. Eseguite
npm run downloadLocalese fate il redeploy.
Quest'ultimo punto è il compromesso. Un giro «traduzione pubblicata in Locize → gli utenti finali la vedono» significa rilanciare la build. Se preferite un fetch live tramite CDN (pubblicate → la pagina successiva lo prende, senza redeploy), montate una framework island e usate i18next-locize-backend al suo interno; il walkthrough di React Router v7 copre quella forma, e potete adottare lo stesso pattern per-island in Astro. Ci torneremo alla fine.
Iniziamo
Prerequisiti
Node.js 22.23.4+ (Astro 7 lo richiede), npm/pnpm/yarn e una familiarità di base con Astro. L'esempio sotto punta ad Astro 7.4 e i18next 27.
Layout del progetto
Generate una nuova app Astro, oppure fate git clone dell'esempio:
npm create astro@latest my-app
cd my-appLa forma della directory rilevante dopo aver cablato i18n + Locize:
my-app/
├── astro.config.mjs # Astro's built-in i18n config
├── package.json # locize-cli download/sync scripts
└── src/
├── pages/
│ ├── index.astro # root /, redirects to /en/
│ └── [lang]/
│ ├── index.astro # home, renders for each locale via getStaticPaths
│ └── second.astro # secondary page, same pattern
├── layouts/
│ └── Layout.astro # shared <html>/<head>/<body>
├── components/
│ └── LanguagePicker.astro # swaps the /{lang}/ prefix
└── i18n/
├── index.ts # loads the JSON into i18next; getT + pathForLang
└── locales/ # locize-cli download target (one JSON per ns)
├── en/
│ ├── common.json
│ ├── index.json
│ └── second.json
└── de/
├── common.json
├── index.json
└── second.jsonInstallare le dipendenze
npm install astro i18next
npm install --save-dev locize-cliNon serve alcun pacchetto di integrazione per Astro: i18next così com'è funziona nei file .astro. È l'unica dipendenza a runtime, e in una build statica gira solo mentre il sito viene costruito.
Configurare l'i18n integrato di Astro in astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
site: 'https://example.com', // your domain: the hreflang links need absolute URLs
i18n: {
defaultLocale: 'en',
locales: ['en', 'de'],
routing: {
prefixDefaultLocale: true // /en/, /de/ # uniform URLs
}
}
})Astro ora possiede:
- Il routing URL per ogni pagina sotto
src/pages/[lang]/:/en/,/de/,/en/second,/de/second, ecc. Astro.currentLocaledisponibile gratuitamente in ogni pagina/componente.- Rilevamento della lingua del browser via
Astro.preferredLocaleeAstro.preferredLocaleList(solo per rotte SSR/on-demand).
Con prefixDefaultLocale: true, ogni locale ottiene un prefisso URL: uniforme, pulito per la SEO e facile da gestire con rotte dinamiche [lang]/ + getStaticPaths. (Se preferite servire la locale di default su / senza prefisso, impostatelo a false e usate pagine file-based invece di [lang]/. L'esempio usa la forma prefissata perché scala meglio.)
Scaricare le traduzioni da Locize al build
Aggiungete a package.json:
{
"scripts": {
"downloadLocales": "locize download --project-id=<your-id> --ver=latest --cdn-type=standard --clean=true --path=./src/i18n/locales",
"syncLocales": "locize sync --project-id=<your-id> --ver=latest --cdn-type=standard --api-key=<your-write-key> --path=./src/i18n/locales --dry=true"
}
}Eseguite npm run downloadLocales prima di npm run build (manualmente, in CI o come hook prebuild) così che i JSON in bundle siano sempre freschi.
Standard vs Pro CDN. Locize offre due infrastrutture CDN (confronto completo in Tipi di CDN: Standard vs Pro): Standard su
api.lite.locize.appè basato su BunnyCDN, gratuito per volumi mensili di download generosi, solo pubblico (default per i nuovi progetti); Pro suapi.locize.appè basato su CloudFront, a pagamento, supporta Private Downloads + controllo cache personalizzato. Allineate--cdn-typenel flag CLI a ciò che è configurato nel vostro progetto.
i18next in src/i18n/index.ts
Locize emette un JSON per namespace per lingua, che è esattamente il modo in cui i18next organizza le sue risorse. Un unico modulo carica ogni file scaricato e inizializza i18next una sola volta:
import i18next, { type Namespace } from 'i18next'
// Every file locize-cli downloads: ./locales/{lng}/{ns}.json
const files = import.meta.glob<{ default: Record<string, string> }>('./locales/*/*.json', { eager: true })
const resources: Record<string, Record<string, Record<string, string>>> = {}
for (const [path, mod] of Object.entries(files)) {
const [, lng, ns] = path.match(/\.\/locales\/([^/]+)\/([^/]+)\.json$/)!
resources[lng] ??= {}
resources[lng][ns] = mod.default
}
export const languages = { en: 'English', de: 'Deutsch' } as const
export type Lang = keyof typeof languages
export const defaultLang: Lang = 'en'
// An instance of its own, apart from any island that uses i18next in the browser.
const i18n = i18next.createInstance()
i18n.init({
resources, // bundled, so init finishes right away
fallbackLng: defaultLang,
defaultNS: 'common',
interpolation: { escapeValue: false } // Astro escapes what {t(...)} renders
})
// A t() bound to one language (and optionally one namespace).
export const getT = <N extends Namespace>(lang: Lang, ns?: N) => i18n.getFixedT(lang, ns)
// The same page in another language: swap the /{lang}/ prefix.
// "/en/second/" → "/de/second/"
export function pathForLang (pathname: string, target: Lang): string {
const parts = pathname.split('/')
parts[1] = target
return parts.join('/')
}Ecco cosa vi offre:
- Nessuna lista di import da mantenere.
import.meta.globraccoglie ogni file chelocize-cliscarica, quindi un nuovo namespace o una nuova lingua da Locize non richiede modifiche al codice (solo la lingua inlocalesinastro.config.mjse un'etichetta inlanguages). - Namespace come file.
getT(lang, 'index')restituisce unat()per una lingua e un namespace; le chiavi di un altro namespace prendono un prefisso:t('common:headTitle'). - Fallback. Una chiave mancante in tedesco ricade sull'inglese (
fallbackLng). - Interpolazione e plurali nel formato che Locize salva per default (i18next JSON v4):
{{name}}per i valori, suffissi_one/_otherpiùcountper i plurali, con le regole di plurale di ogni lingua:
{
"title": "Hello, {{name}}!",
"loaves_one": "{{count}} loaf left",
"loaves_other": "{{count}} loaves left"
}Funzionano anche le chiavi tipizzate: il supporto TypeScript di i18next legge i nomi delle chiavi dal JSON della vostra lingua di default.
Usare t() nelle pagine
Le rotte dinamiche [lang]/ + getStaticPaths fanno sì che Astro pre-renderizzi un file HTML per ciascuna locale al build:
---
// src/pages/[lang]/index.astro (excerpt)
import Layout from '../../layouts/Layout.astro'
import { getT, languages, type Lang } from '../../i18n'
import { getRelativeLocaleUrl } from 'astro:i18n'
export function getStaticPaths () {
return Object.keys(languages).map(lang => ({ params: { lang } }))
}
const { lang } = Astro.params as { lang: Lang }
const t = getT(lang, 'index')
---
<Layout lang={lang} title={t('common:headTitle')}>
<h1>{t('title', { name: 'Astro' })}</h1>
<p>{t('subtitle')}</p>
<p>{t('loaves', { count: 1 })} · {t('loaves', { count: 3 })}</p>
<p>
<a href={getRelativeLocaleUrl(lang, 'second/')}>
{t('goto.second')}
</a>
</p>
</Layout>La funzione getStaticPaths mappa ogni locale a un percorso statico; lang arriva come parametro di rotta. Lavoro puramente al build: nessun runtime lato server, nessuna hydration. La build scrive /en/index.html con "Hello, Astro!" e "1 loaf left · 3 loaves left", e /de/index.html con "Hallo, Astro!" e "1 Brot übrig · 3 Brote übrig", e nessun file JavaScript.
Il language picker e i link hreflang
La ricetta i18n dei docs di Astro mostra un picker semplice che scambia il prefisso di locale sulla URL corrente; dello scambio si occupa pathForLang di src/i18n/index.ts:
---
// src/components/LanguagePicker.astro (excerpt)
import { languages, pathForLang, type Lang } from '../i18n'
interface Props {
currentLang: Lang
}
const { currentLang } = Astro.props
---
<nav>
<ul>
{Object.entries(languages).map(([lang, label]) => (
<li>
{lang === currentLang ? (
<strong>{label}</strong>
) : (
<a href={pathForLang(Astro.url.pathname, lang as Lang)}>{label}</a>
)}
</li>
))}
</ul>
</nav>Inseritelo in src/layouts/Layout.astro e sarà disponibile su ogni pagina. Lo stesso layout scrive i link hreflang, così i motori di ricerca sanno quale pagina è in quale lingua; il routing di Astro non li aggiunge:
---
// src/layouts/Layout.astro (head excerpt)
import { languages, defaultLang, pathForLang, type Lang } from '../i18n'
const { lang, title } = Astro.props
---
<html lang={lang}>
<head>
<title>{title}</title>
{Object.keys(languages).map(l => (
<link rel="alternate" hreflang={l} href={new URL(pathForLang(Astro.url.pathname, l as Lang), Astro.site)} />
))}
<link rel="alternate" hreflang="x-default" href={new URL(pathForLang(Astro.url.pathname, defaultLang), Astro.site)} />
</head>Tre modi per far arrivare nuove chiavi in Locize
Astro è static-by-default: le pagine sono pre-renderizzate, quindi un push saveMissing a runtime dagli utenti in produzione non è possibile senza un adapter SSR, e comunque Astro scoraggia le scritture dal layer statico. Ci sono invece tre strade praticabili:
npm run syncLocales(cablato inpackage.json, togliete il flag--dry=trueper spingere davvero).locize-clilegge i vostrisrc/i18n/locales/{lng}/{ns}.jsonlocali e carica qualsiasi chiave non ancora in Locize. Manuale o triggerato da CI, nessuna write-key nel browser.- Estrazione statica via
i18next-cli: trova di serie le chiamatet('…')nei file.js,.ts,.jsxe.tsxe scrive le nuove chiavi nei JSON locali, poi sync verso l'alto come sopra. I file.astrorichiedono un plugin tramite i suoi hook per i plugin; senza un plugin, i18next-cli non li legge. - L'app web di Locize: aggiungete chiavi direttamente nell'editor e portatele giù con
downloadLocalesprima della prossima build.
Scegliete quella che si adatta al vostro workflow. Nessuna richiede di spedire una write API key nel vostro artefatto di build.
Cosa questa forma intenzionalmente non include
Tre cose che potreste aspettarvi dai walkthrough di Nuxt o React Router v7 sono deliberatamente assenti qui:
- Nessun
saveMissinga runtime. Vedete sopra: le build statiche di Astro non possono spingere, e un'app Astro SSR lo farebbe da dentro un'island, non dal layer statico. - Nessun editor in-context sulle pagine statiche. L'editor di
locizeha bisogno di un DOM che si re-renderizzi quando l'editor aggiorna una stringa. L'output statico di Astro non ha quel gancio. - Nessun fetch live tramite CDN. Le traduzioni sono messe in bundle al build. Per servire una traduzione fresca, eseguite
npm run downloadLocalese fate il redeploy. Questo si allinea al modello static-first di Astro e mantiene l'artefatto di build autocontenuto.
Tutte e tre funzionano dentro le framework island. Montate un'island React, Vue, Svelte, Solid o Preact tramite la corrispondente integrazione @astrojs/<framework>, e dentro quell'island usate i18next-locize-backend + il pacchetto locize direttamente. Il layer statico di Astro gestisce il routing + il chrome della pagina; le island gestiscono le parti che richiedono un runtime. Pagine e island usano la stessa libreria e lo stesso formato JSON.
Quando aggiungere una framework island
L'integrazione solo-statica copre la maggior parte dei siti di contenuto: blog, pagine marketing, docs, landing page. Aggiungete una framework island quando vi serve:
- Aggiornamenti di traduzione live senza redeploy. Usate
i18next-locize-backenddentro l'island per recuperare le traduzioni dal CDN di Locize a ogni visita (o per rotta, se mettete in cache). - Editing in-context per i traduttori. L'overlay
?incontext=truedel pacchettolocizeha bisogno di un runtime che si re-renderizzi sui cambi di stringa, disponibile solo dentro un'island idratata. saveMissinga runtime. Stesso vincolo: un'island idratata può spingere nuove chiavi; l'HTML statico no.
Il pattern appare così (per un'island React):
---
// src/pages/[lang]/interactive.astro
import Layout from '../../layouts/Layout.astro'
import I18nIsland from '../../components/I18nIsland.tsx'
import { languages, type Lang } from '../../i18n'
export function getStaticPaths () {
return Object.keys(languages).map(lang => ({ params: { lang } }))
}
const { lang } = Astro.params as { lang: Lang }
---
<Layout lang={lang} title="Interactive">
<I18nIsland client:load lang={lang} />
</Layout>// src/components/I18nIsland.tsx
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import { initReactI18next, useTranslation } from 'react-i18next'
i18next
.use(Backend)
.use(initReactI18next)
.init({
fallbackLng: 'en',
saveMissing: import.meta.env.DEV,
backend: {
projectId: import.meta.env.PUBLIC_LOCIZE_PROJECT_ID,
apiKey: import.meta.env.DEV ? import.meta.env.PUBLIC_LOCIZE_API_KEY : undefined, // dev only; the browser sees only PUBLIC_ variables
version: 'latest'
}
})
export default function I18nIsland ({ lang }: { lang: string }) {
const { t, i18n } = useTranslation()
if (i18n.language !== lang) i18n.changeLanguage(lang)
return <h2>{t('island.heading')}</h2>
}client:load dice ad Astro di idratare questo componente immediatamente al caricamento della pagina; potete usare client:visible per posticipare l'hydration finché l'island non entra nel viewport. La configurazione precisa di i18next-locize-backend è documentata nel walkthrough di React Router v7; lo stesso cablaggio del backend funziona in qualsiasi contesto React/Vue/Svelte/Solid, incluso dentro un'island Astro.
🎉 Complimenti
Un setup funzionante Astro 7 + i18next + Locize vi offre:
- i18n static-first senza flash di contenuti non tradotti e senza JavaScript di traduzione nel browser (tutto è pre-renderizzato per locale)
- Prefissazione URL pulita per la SEO via il routing i18n integrato di Astro, con i link hreflang dal layout
- Una
t()completa da i18next: plurali, interpolazione, fallback, namespace - Sincronizzazione delle traduzioni al build via
locize-cli: serverless-friendly, nessun hop CDN per richiesta - Una via di fuga verso island dinamiche, con la stessa libreria e gli stessi file, quando vi servono aggiornamenti a runtime o editing in-context
🧑💻 Il codice completo: github.com/locize/locize-astro-example.
I fondatori di Locize sono anche i creatori di i18next. Usando Locize sostenete direttamente il futuro di i18next.
Vedete anche
- Come internazionalizzare un'app Nuxt 4 con @nuxtjs/i18n e Locize: controparte lato Vue con integrazione più ricca (vue-i18n, editor in-context, saveMissing a runtime)
- Come internazionalizzare un'app React Router v7 con remix-i18next: controparte lato React con fetch live tramite CDN via
i18next-locize-backend - Routing i18n integrato di Astro: la primitiva di routing su cui questo walkthrough si fonda
- Ricetta i18n di Astro: il pattern build-it-yourself che qui i18next sostituisce
- Documentazione di i18next:
t(), plurali, interpolazione, TypeScript locize-cli: lo strumento di sincronizzazione al build
Stanchi di gestire le traduzioni a mano?
Locize è il backend di gestione delle traduzioni creato dal team di i18next: distribuzione via CDN, traduzione con AI, editing in-context, senza nuovi deploy.
Iniziate la prova gratuita di 14 giorni
