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

Inhaltsverzeichnis

Warum Intlayer gegenüber Alternativen?

Im Vergleich zu Hauptlösungen wie „lit-localize“ oder „i18next“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:

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

1. 1

   Abhängigkeiten installieren

   Installieren Sie die erforderlichen Pakete mit npm:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

2. 2

   Konfiguration Ihres Projekts

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

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

3. 3

   Intlayer in Ihre Vite-Konfiguration integrieren

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

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

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

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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:

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

5. 5

   Ihre Inhalte deklarieren

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

   src/app.content.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

   Weitere Einzelheiten finden Sie in der Dokumentation zur Inhaltsdeklaration.

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

   src/my-element.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

7. 7

   Die Sprache Ihres Inhalts ändern

   Optional

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

   src/locale-switcher.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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

   Markdown- und HTML-Inhalte rendern

   Optional

   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:

   src/my-element.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

9. 9

   Localized Routing zu Ihrer Anwendung hinzufügen

   Optional

   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.

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

10. 10

    Die URL ändern, wenn sich die Sprache ändert

    Optional

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

    src/locale-switcher.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

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

11. 11

    HTML-Sprach- und Richtungsattribute umschalten

    Optional

    Aktualisieren Sie die Attribute lang und dir des <html>-Tags entsprechend der aktuellen Sprache für Barrierefreiheit und SEO.

    src/my-element.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

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

12. 12

    Den Inhalt Ihrer Komponenten extrahieren

    Optional

    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:

    intlayer.config.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    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.