Übersetzen Sie Ihre Vite- und Lit-Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Was ist Intlayer?

Intlayer ist eine innovative Open-Source-Internationalisierungsbibliothek (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen.

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten mithilfe deklarativer Wörterbücher auf Komponentenebene.
• Metadaten, Routen und Inhalte dynamisch lokalisieren.
• TypeScript-Unterstützung sicherstellen mit automatisch generierten Typen, was die Autovervollständigung und Fehlererkennung verbessert.
• Von erweiterten Funktionen profitieren, wie dynamischer Spracherkennung und -umschaltung.

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Vite- und Lit-Anwendung

Schritt 1: Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete mit npm:

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

• intlayer

  Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

• lit-intlayer Das Paket, das Intlayer in Lit-Anwendungen integriert. Es bietet auf ReactiveController basierende Hooks (useIntlayer, useLocale usw.), sodass LitElements automatisch neu gerendert werden, wenn sich die Sprache ändert.

• vite-intlayer Enthält das Vite-Plugin zur Integration von Intlayer in den Vite-Bundler sowie Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

Schritt 2: Konfiguration Ihres Projekts

Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:

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

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

export default config;

Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Ort und die Erweiterung Ihrer Inhaltsdeklarationen festlegen, Intlayer-Protokolle in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

Schritt 3: Intlayer in Ihre Vite-Konfiguration integrieren

Fügen Sie das Intlayer-Plugin in Ihre Konfiguration ein.

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

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

Das intlayer() Vite-Plugin wird verwendet, um Intlayer in Vite zu integrieren. Es stellt die Erstellung von Inhaltsdeklarationsdateien sicher und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Darüber hinaus bietet es Aliase zur Leistungsoptimierung.

Schritt 4: Intlayer in Ihrem Einstiegspunkt initialisieren

Rufen Sie installIntlayer() auf, bevor benutzerdefinierte Elemente registriert werden, damit das globale Sprach-Singleton bereit ist, wenn sich das erste Element verbindet.

import { installIntlayer } from "lit-intlayer";// Muss aufgerufen werden, bevor ein LitElement mit dem DOM verbunden wird.installIntlayer();// Importieren und registrieren Sie Ihre benutzerdefinierten Elemente.import "./my-element.js";

Wenn Sie auch md() Inhaltsdeklarationen (Markdown) verwenden, installieren Sie zusätzlich den Markdown-Renderer:

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

Schritt 5: Ihre Inhalte deklarieren

Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

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;

Ihre Inhaltsdeklarationen können an beliebiger Stelle in Ihrer Anwendung definiert werden, sofern sie im Verzeichnis contentDir (standardmäßig ./src) enthalten sind und der Dateierweiterung für Inhaltsdeklarationen entsprechen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Weitere Einzelheiten finden Sie in der Dokumentation zur Inhaltsdeklaration.

Schritt 6: Intlayer in Ihrem LitElement verwenden

Verwenden Sie useIntlayer innerhalb eines LitElement. Es gibt einen ReactiveController-Proxy zurück, der automatisch Neu-Renderings auslöst, sobald sich die aktive Sprache ändert – keine zusätzliche Einrichtung erforderlich.

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 registriert sich als ReactiveController.  // Das Element wird automatisch neu gerendert, wenn sich die Sprache ändert.  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>    `;  }}

Wenn Sie den übersetzten String in einem nativen HTML-Attribut benötigen (z. B. alt, aria-label, title), rufen Sie .value auf dem Blattknoten auf:

typescript

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

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

(Optional) Schritt 7: Die Sprache Ihres Inhalts ändern

Um die Sprache Ihres Inhalts zu ändern, verwenden Sie die Methode setLocale, welche vom useLocale-Controller bereitgestellt wird.

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

(Optional) Schritt 8: Markdown- und HTML-Inhalte rendern

Intlayer unterstützt md() und html() Inhaltsdeklarationen. In Lit wird die kompilierte Ausgabe als rohes HTML über die unsafeHTML-Direktive eingefügt.

Rendern Sie das kompilierte HTML in Ihrem Element:

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) ruft toString() auf dem IntlayerNode auf, was den rohen Markdown-String zurückgibt. Übergeben Sie diesen an compileMarkdown, um einen HTML-String zu erhalten, und rendern Sie ihn dann mit Lits unsafeHTML-Direktive.

(Optional) Schritt 9: Localized Routing zu Ihrer Anwendung hinzufügen

Um eindeutige Routen für jede Sprache zu erstellen (nützlich für SEO), können Sie einen clientseitigen Router zusammen mit Intlayers localeMap / localeFlatMap Helfern und dem intlayerProxy Vite-Plugin für die serverseitige Spracherkennung verwenden.

Fügen Sie zuerst intlayerProxy zu Ihrer Vite-Konfiguration hinzu:

Beachten Sie, dass Sie zur Verwendung von intlayerProxy in der Produktion vite-intlayer von devDependencies zu dependencies verschieben müssen.

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

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

(Optional) Schritt 10: Die URL ändern, wenn sich die Sprache ändert

Um die Browser-URL zu aktualisieren, wenn sich die Sprache ändert, verwenden Sie useRewriteURL zusammen mit dem Sprachumschalter:

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);  // Schreibt die aktuelle URL automatisch um, wenn sich die Sprache ändert.  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>    `;  }}

(Optional) Schritt 11: HTML-Sprach- und Richtungsattribute umschalten

Aktualisieren Sie die Attribute lang und dir des <html>-Tags entsprechend der aktuellen Sprache für Barrierefreiheit und 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`<!-- Ihr Inhalt -->`;  }}

(Optional) Schritt 12: Den Inhalt Ihrer Komponenten extrahieren

Wenn Sie eine bestehende Codebasis haben, kann das Transformieren von Tausenden von Dateien zeitaufwendig sein.

Um diesen Prozess zu erleichtern, bietet Intlayer einen Compiler / Extractor an, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.

Um dies einzurichten, können Sie einen compiler-Abschnitt in Ihrer intlayer.config.ts-Datei hinzufügen:

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Rest Ihrer Konfiguration  compiler: {    /**     * Gibt an, ob der Compiler aktiviert sein soll.     */    enabled: true,    /**     * Definiert den Pfad der Ausgabedateien     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen.     * Auf diese Weise kann der Compiler nur einmal ausgeführt werden, um die App zu transformieren, und kann dann entfernt werden.     */    saveComponents: false,    /**     * Wörterbuch-Schlüsselpräfix     */    dictionaryKeyPrefix: "",  },};export default config;

(Optional) Sitemap und robots.txt (Build-Zeit)

Intlayer stellt Hilfsfunktionen bereit - generateSitemap und getMultilingualUrls -, mit denen Sie mehrsprachige sitemap.xml- und robots.txt-Inhalte für Crawler formatieren und automatisch nach public/ schreiben können. Üblich ist ein kleines Node-Skript vor Vite (z. B. npm-predev-/prebuild-Hooks), damit die Dateien beim Build bzw. Dev-Server vorliegen.

Sitemap

Der Sitemap-Generator von Intlayer berücksichtigt Ihre Locales und die üblichen Metadaten für Crawler.

Die erzeugte Sitemap unterstützt den xhtml:link-Namensraum (Hreflang). Statt nur flacher URLs verknüpft Intlayer alle Sprachversionen einer Seite bidirektional (z. B. /about, /fr/about oder /about?lang=fr je nach Routing), was Suchmaschinen hilft.

Robots.txt

Mit getMultilingualUrls gelten Disallow-Regeln für alle lokalisierten Varianten sensibler Pfade.

1. generate-seo.mjs im Projektroot anlegen

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.");

intlayer muss installiert sein. Setzen Sie SITE_URL in der Produktion über die Umgebung (z. B. in der CI).

Nutzen Sie möglichst generate-seo.mjs für Node-ESM. Bei generate-seo.js "type": "module" in der package.json setzen oder Node mit ESM starten.

2. Skript vor Vite ausführen

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

Bei pnpm oder yarn die Befehle anpassen. Aufruf aus der CI ist ebenfalls möglich.

TypeScript konfigurieren

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält.

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

experimentalDecorators und useDefineForClassFields: false werden von Lit für die Unterstützung von Dekoratoren benötigt.

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dies ermöglicht es Ihnen, zu vermeiden, sie in Ihr Git-Repository zu übertragen.

Dazu können Sie die folgenden Anweisungen zu Ihrer .gitignore-Datei hinzufügen:

# Die von Intlayer generierten Dateien ignorieren.intlayer

VS Code Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Erweiterung installieren.

Installation über den VS Code Marketplace

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen von übersetzten Inhalten.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Weitere Details zur Verwendung der Erweiterung finden Sie in der Dokumentation zur Intlayer VS Code Erweiterung.

Weiterführende Schritte

Um tiefer einzusteigen, können Sie den Visual Editor implementieren oder Ihre Inhalte mithilfe des CMS extern verwalten.