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

Sommario

Perché Intlayer rispetto alle alternative?

Rispetto alle soluzioni principali come lit-localize o i18next, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

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

1. 1

   Installare le dipendenze

   Installa i pacchetti necessari utilizzando npm:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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.

2. 2

   Configurazione del progetto

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

   intlayer.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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.

3. 3

   Integrare Intlayer nella configurazione di Vite

   Aggiungi il plugin intlayer nella tua configurazione.

   vite.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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.

4. 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.

   src/main.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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:

   src/main.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

5. 5

   Dichiarare il contenuto

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

   src/app.content.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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,md,mdx,yaml,yml}).

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

6. 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.

   src/my-element.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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)} />`;

7. 7

   Cambiare la lingua del contenuto

   Opzionale

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

   src/locale-switcher.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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>    `;  }}

8. 8

   Renderizzare contenuti Markdown e HTML

   Opzionale

   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:

   src/my-element.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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.

9. 9

   Aggiungere il routing localizzato alla tua applicazione

   Opzionale

   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.

   vite.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

10. 10

    Cambiare l'URL quando la lingua cambia

    Opzionale

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

    src/locale-switcher.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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>    `;  }}

11. 11

    Commutare gli attributi di lingua e direzione HTML

    Opzionale

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

    src/my-element.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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 -->`;  }}

12. 12

    Estrarre il contenuto dei tuoi componenti

    Opzionale

    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:

    intlayer.config.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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.