Ricevi notifiche sui prossimi lanci di Intlayer
    Creazione:2024-03-07Ultimo aggiornamento:2025-10-03

    Iniziare con l'internazionalizzazione (i18n) usando Intlayer e Astro

    Consulta il Template dell'Applicazione su GitHub.

    Cos'è Intlayer?

    Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle moderne applicazioni web.

    Con Intlayer, puoi:

    • Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
    • Localizzare dinamicamente i metadata, le rotte e i contenuti.
    • Garantire il supporto a TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
    • Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.

    Guida passo-passo per configurare Intlayer in Astro

    Passo 1: Installa le dipendenze

    Installa i pacchetti necessari usando il tuo gestore di pacchetti:

    npm install intlayer astro-intlayer# Optional: add React island supportnpm install react react-dom react-intlayer @astrojs/react

    • intlayer Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, la traduzione, la dichiarazione dei contenuti, la traspilazione e i comandi CLI.

    • astro-intlayer Include il plugin di integrazione Astro per integrare Intlayer con il bundler Vite, oltre a middleware per rilevare la lingua preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.

    Passo 2: Configurazione del tuo progetto

    Crea un file di configurazione per configurare le lingue della tua applicazione:

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Le tue altre lingue    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

    Attraverso questo file di configurazione, puoi impostare URL localizzati, il reindirizzamento del middleware, i nomi dei cookie, la posizione e l'estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.

    Passo 3: Integra Intlayer nella tua configurazione Astro

    Aggiungi il plugin intlayer nella tua configurazione.

    astro.config.ts
    // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});

    Il plugin di integrazione intlayer() per Astro viene utilizzato per integrare Intlayer con Astro. Garantisce la creazione dei file di dichiarazione del contenuto e li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno dell'applicazione Astro. Inoltre, fornisce alias per ottimizzare le prestazioni.

    Passo 4: Dichiara il tuo contenuto

    Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

    src/app.content.tsx
    import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",    }),  },} satisfies Dictionary;export default appContent;

    Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena sono incluse nella directory contentDir (di default, ./src). E devono corrispondere all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

    Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

    Passo 5: Usa il tuo contenuto in Astro

    Puoi utilizzare i dizionari direttamente nei file .astro usando gli helper core esportati da intlayer.

    src/pages/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";import appContent from "../app.content";const { title } = getIntlayer('app');---<html lang="en">  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <title>{title}</title>  </head>  <body>    <h1>{title}</h1>  </body></html>

    Passo 6: Routing localizzato

    Crea un segmento di route dinamico per servire pagine localizzate, ad esempio src/pages/[locale]/index.astro:

    src/pages/[locale]/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

    L'integrazione con Astro aggiunge un middleware Vite durante lo sviluppo che aiuta con il routing consapevole della localizzazione e le definizioni dell'ambiente. Puoi comunque collegarti tra le localizzazioni usando la tua logica o funzioni di utilità come getLocalizedUrl da intlayer.

    Passo 7: Continua a usare il tuo framework preferito

    Continua a usare il tuo framework preferito per costruire la tua applicazione.

    Configurare TypeScript

    Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.

    Autocompletion

    Translation error

    Assicurati che la tua configurazione di TypeScript includa i tipi generati automaticamente.

    tsconfig.json
    {  // ... Le tue configurazioni TypeScript esistenti  "include": [    // ... Le tue configurazioni TypeScript esistenti    ".intlayer/**/*.ts", // Includi i tipi generati automaticamente  ],}

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di committarli nel tuo repository Git.

    Per fare ciò, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

    # Ignora i file generati da Intlayer.intlayer

    Estensione VS Code

    Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'Estensione ufficiale Intlayer per VS Code.

    Installa dal Marketplace di VS Code

    Questa estensione offre:

    • Completamento automatico per le chiavi di traduzione.
    • Rilevamento errori in tempo reale per traduzioni mancanti.
    • Anteprime inline del contenuto tradotto.
    • Azioni rapide per creare e aggiornare facilmente le traduzioni.

    Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'Estensione Intlayer per VS Code.

    Vai oltre

    Per andare oltre, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.

    Cronologia della documentazione

    Versione Data Modifiche
    6.2.0 2025-10-03 Aggiornamento per integrazione Astro, configurazione, utilizzo
    Tanstack Start
    React CRA
    Ricevi notifiche sui prossimi lanci di Intlayer