Traduci il tuo sito web Vite e Lit usando Intlayer | Internazionalizzazione (i18n)

Sommario

Cos'è Intlayer?

Intlayer è un'innovativa libreria di internazionalizzazione (i18n) open-source 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 metadati, rotte e contenuti.
• Garantire il supporto TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
• Beneficiare di funzionalità avanzate, come il rilevamento e la commutazione dinamica della lingua.

Guida passo-passo per configurare Intlayer in un'applicazione Vite e Lit

Passaggio 1: Installare le dipendenze

Installa i pacchetti necessari utilizzando npm:

npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

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

• lit-intlayer Il pacchetto che integra Intlayer con le applicazioni Lit. Fornisce hook basati su ReactiveController (useIntlayer, useLocale, ecc.) in modo che i LitElement si ri-renderizzino automaticamente quando la lingua cambia.

• vite-intlayer Include il plugin Vite per integrare Intlayer con il bundler Vite, oltre al middleware per rilevare la lingua preferita dell'utente, gestire i cookie e gestire il reindirizzamento degli URL.

Passaggio 2: Configurazione del progetto

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

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Altre lingue
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamento middleware, 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 sulla configurazione.

Passaggio 3: Integrare Intlayer nella configurazione di Vite

Aggiungi il plugin intlayer nella tua configurazione.

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

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

Passaggio 4: Bootstrap di Intlayer nel tuo punto di ingresso

Chiama installIntlayer() prima che vengano registrati elementi personalizzati, in modo che il singleton globale della lingua sia pronto quando il primo elemento si connette.

import { installIntlayer } from "lit-intlayer";// Deve essere chiamato prima che qualsiasi LitElement sia connesso al DOM.installIntlayer();// Importa e registra i tuoi elementi personalizzati.import "./my-element.js";

Se utilizzi anche dichiarazioni di contenuto md() (Markdown), installa anche il renderer markdown:

import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

Passaggio 5: Dichiarare il contenuto

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

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Lit",

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

    count: t({
      en: "count is {{count}}",
      fr: "le compte est {{count}}",
      es: "el recuento es {{count}}",
    }),

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

Le dichiarazioni di contenuto possono essere definite ovunque nell'applicazione, purché siano incluse nella cartella contentDir (per impostazione predefinita, ./src) e corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Per ulteriori dettagli, consulta la documentazione sulla dichiarazione dei contenuti.

Passaggio 6: Utilizzare Intlayer nel tuo LitElement

Usa useIntlayer all'interno di un LitElement. Restituisce un proxy ReactiveController che attiva automaticamente i re-render ogni volta che la lingua attiva cambia: non è richiesta alcuna configurazione aggiuntiva.

import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer si registra come ReactiveController.  // L'elemento si ri-renderizza automaticamente quando la lingua cambia.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

Quando hai bisogno della stringa tradotta in un attributo HTML nativo (es. alt, aria-label, title), chiama .value sul nodo foglia:

typescript

Copia contenuto

Copiare il codice

Copiare il codice nella clipboard

html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

(Opzionale) Passaggio 7: Cambiare la lingua del contenuto

Per cambiare la lingua del contenuto, usa il metodo setLocale esposto dal controller useLocale.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Opzionale) Passaggio 8: Renderizzare contenuti Markdown e HTML

Intlayer supporta le dichiarazioni di contenuto md() e html(). In Lit, l'output compilato viene iniettato come HTML grezzo tramite la direttiva unsafeHTML.

Renderizza l'HTML compilato nel tuo elemento:

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}

TIP

String(content.editNote) chiama toString() sull'IntlayerNode, che restituisce la stringa Markdown grezza. Passala a compileMarkdown per ottenere una stringa HTML, quindi caricala con la direttiva unsafeHTML di Lit.

(Opzionale) Passaggio 9: Aggiungere il routing localizzato alla tua applicazione

Per creare rotte uniche per ogni lingua (utile per la SEO), puoi utilizzare un router lato client insieme agli helper localeMap / localeFlatMap di Intlayer e al plugin Vite intlayerProxy per il rilevamento della lingua lato server.

Innanzitutto, aggiungi intlayerProxy alla tua configurazione Vite:

Nota che per utilizzare intlayerProxy in produzione, devi spostare vite-intlayer da devDependencies a dependencies.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // should be placed first
    intlayer(),
  ],
});

(Opzionale) Passaggio 10: Cambiare l'URL quando la lingua cambia

Per aggiornare l'URL del browser quando la lingua cambia, utilizza useRewriteURL insieme al selettore di lingua:

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Riscrive automaticamente l'URL corrente quando la lingua cambia.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Opzionale) Passaggio 11: Commutare gli attributi di lingua e direzione HTML

Aggiorna gli attributi lang e dir del tag <html> per farli corrispondere alla lingua corrente per l'accessibilità e la SEO.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- il tuo contenuto -->`;  }}

(Opzionale) Passaggio 12: Estrarre il contenuto dei tuoi componenti

Se hai una base di codice esistente, trasformare migliaia di file può richiedere molto tempo.

Per facilitare questo processo, Intlayer propone un compilatore / estrattore per trasformare i tuoi componenti ed estrarre il contenuto.

Per configurarlo, puoi aggiungere una sezione compiler nel tuo file intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Resto della tua configurazione  compiler: {    /**     * Indica se il compilatore deve essere abilitato.     */    enabled: true,    /**     * Definisce il percorso dei file di output     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Indica se i componenti devono essere salvati dopo essere stati trasformati.     * In questo modo, il compilatore può essere eseguito una sola volta per trasformare l'app e poi può essere rimosso.     */    saveComponents: false,    /**     * Prefisso della chiave del dizionario     */    dictionaryKeyPrefix: "",  },};export default config;

(Opzionale) Sitemap e robots.txt (generazione in build)

Intlayer espone utilità - generateSitemap e getMultilingualUrls - per formattare sitemap.xml multilingue e robots.txt pronti per i crawler e scriverli automaticamente in public/. Di solito si esegue un piccolo script Node prima di Vite (ad esempio hook npm predev / prebuild) così che i file siano presenti in build o in sviluppo.

Sitemap

Il generatore di sitemap di Intlayer rispetta le tue lingue e aggiunge i metadati attesi dai crawler.

La sitemap supporta lo spazio dei nomi xhtml:link (hreflang). Invece di elencare solo URL “piatti”, Intlayer collega in modo bidirezionale tutte le versioni linguistiche di ogni pagina (ad es. /about, /fr/about o /about?lang=fr a seconda del routing).

Robots.txt

Usa getMultilingualUrls così le regole Disallow coprono tutte le varianti localizzate dei percorsi sensibili.

1. Aggiungi generate-seo.mjs nella root del progetto

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Serve il pacchetto intlayer installato. Imposta SITE_URL in ambiente per la produzione (es. in CI).

Preferisci generate-seo.mjs per l’ESM di Node. Con generate-seo.js imposta "type": "module" in package.json oppure abilita l’ESM in Node.

2. Esegui lo script prima di Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Adatta i comandi se usi pnpm o yarn. Puoi anche richiamare lo script dalla CI o da un altro passo del pipeline.

Configurare TypeScript

Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

{  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}

experimentalDecorators e useDefineForClassFields: false sono richiesti da Lit per il supporto dei decoratori.

Configurazione Git

Si consiglia di ignorare i file generati da Intlayer. Ciò consente di evitare di caricarli nel repository Git.

Per farlo, 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 VS Code Marketplace

Questa estensione fornisce:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento degli errori in tempo reale per le 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 approfondire, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.