Andate al contenuto
Tutorials21 maggio 2026· Aggiornato 17 novembre 2026· 9 min di lettura

Internazionalizzare un sito Astro con i18next e Locize

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: true per URL uniformi.
  • Usate rotte di pagina dinamiche [lang]/ con getStaticPaths così che ogni locale venga pre-renderizzata staticamente.
  • Sincronizzate le traduzioni nell'app al build tramite il comando download di locize-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 una t() per la propria lingua con getFixedT. 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 syncLocales o l'app web di Locize, a seconda di cosa si adatta al vostro workflow. Non è possibile un saveMissing a 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 usate i18next-locize-backend + il pacchetto locize dentro 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-cli scarica gli ultimi JSON pubblicati dal CDN di Locize in src/i18n/locales/{lng}/{ns}.json. src/i18n/index.ts carica 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 downloadLocales e 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-app

La 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.json

Installare le dipendenze

npm install astro i18next
npm install --save-dev locize-cli

Non 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.currentLocale disponibile gratuitamente in ogni pagina/componente.
  • Rilevamento della lingua del browser via Astro.preferredLocale e Astro.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 su api.locize.app è basato su CloudFront, a pagamento, supporta Private Downloads + controllo cache personalizzato. Allineate --cdn-type nel 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.glob raccoglie ogni file che locize-cli scarica, quindi un nuovo namespace o una nuova lingua da Locize non richiede modifiche al codice (solo la lingua in locales in astro.config.mjs e un'etichetta in languages).
  • Namespace come file. getT(lang, 'index') restituisce una t() 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 / _other più count per 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.

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:

  1. npm run syncLocales (cablato in package.json, togliete il flag --dry=true per spingere davvero). locize-cli legge i vostri src/i18n/locales/{lng}/{ns}.json locali e carica qualsiasi chiave non ancora in Locize. Manuale o triggerato da CI, nessuna write-key nel browser.
  2. Estrazione statica via i18next-cli: trova di serie le chiamate t('…') nei file .js, .ts, .jsx e .tsx e scrive le nuove chiavi nei JSON locali, poi sync verso l'alto come sopra. I file .astro richiedono un plugin tramite i suoi hook per i plugin; senza un plugin, i18next-cli non li legge.
  3. L'app web di Locize: aggiungete chiavi direttamente nell'editor e portatele giù con downloadLocales prima 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 saveMissing a 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 locize ha 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 downloadLocales e 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-backend dentro 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=true del pacchetto locize ha bisogno di un runtime che si re-renderizzi sui cambi di stringa, disponibile solo dentro un'island idratata.
  • saveMissing a 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

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

Articoli correlati