Übersetzen Sie Ihre Angular 21 (Vite) Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Was ist Intlayer?

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

Mit Intlayer können Sie:

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

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Angular-Anwendung

Siehe Anwendungsvorlage auf GitHub.

Schritt 1: Abhängigkeiten installieren

Installieren Sie die benötigten Pakete über npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

• intlayer

  Das Kernpaket, das Internationalisierungstools für Konfigurationsverwaltung, Übersetzung, Inhaltsdeklaration, Transpilierung und CLI-Befehle bereitstellt.

• angular-intlayer Das Paket, das Intlayer in die Angular-Anwendung integriert. Es stellt Kontextanbieter und Hooks für die Angular-Internationalisierung zur Verfügung.

• @angular-builders/custom-esbuild Erforderlich, um die esbuild-Konfiguration der Angular CLI anzupassen.

Schritt 2: Konfiguration Ihres Projekts

Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung festzulegen:

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 einrichten, Intlayer-Logs 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 Angular-Konfiguration integrieren

Um Intlayer in die Angular CLI zu integrieren, müssen Sie einen benutzerdefinierten Builder verwenden. Diese Anleitung geht davon aus, dass Sie Vite/esbuild verwenden (Standard für Angular 21-Projekte).

Ändern Sie zunächst Ihre angular.json, um den benutzerdefinierten esbuild-Builder zu verwenden. Aktualisieren Sie die Konfigurationen für build und serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

Stellen Sie sicher, dass Sie your-app-name durch den tatsächlichen Namen Ihres Projekts in der angular.json ersetzen.

Erstellen Sie als Nächstes eine esbuild.plugins.ts-Datei im Stammverzeichnis Ihres Projekts:

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Die Funktion intlayerEsbuildPlugin konfiguriert esbuild mit Intlayer. Sie injiziert das Plugin, um Inhaltsdeklarationsdateien zu verarbeiten, und richtet Konfigurationen für optimale Leistung ein.

NX-Benutzer: Die Angular-Builder von NX laden Plugin-Dateien über die native ESM-Auflösung von Node und kompilieren TypeScript-Plugin-Dateien nicht direkt. Verwenden Sie stattdessen eine .mjs-Datei und aktualisieren Sie die plugins-Referenz in angular.json entsprechend:

esbuild.plugins.mjs

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Zeigen Sie dann in angular.json auf "./esbuild.plugins.mjs" anstelle von "./esbuild.plugins.ts".

Schritt 4: Deklarieren Sie Ihre Inhalte

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

Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, solange sie in das Verzeichnis contentDir (standardmäßig ./src) aufgenommen werden. Sie müssen auch der Dateierweiterung für Inhaltsdeklarationen entsprechen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Weitere Details finden Sie in der Dokumentation zur Inhaltsdeklaration.

Schritt 5: Nutzen Sie Intlayer in Ihrem Code

Um die Internationalisierungsfunktionen von Intlayer in Ihrer gesamten Angular-Anwendung zu nutzen, müssen Sie Intlayer in der Anwendungskonfiguration bereitstellen.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Intlayer-Anbieter hier hinzufügen  ],};

Anschließend können Sie die Funktion useIntlayer in einer beliebigen Komponente verwenden.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Und in Ihrem Template:

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

Intlayer-Inhalte werden als Signal zurückgegeben, sodass Sie durch Aufrufen des Signals auf die Werte zugreifen: content().title.

(Optional) Schritt 6: Sprache des Inhalts ändern

Um die Sprache Ihres Inhalts zu ändern, können Sie die Funktion setLocale nutzen, die von der Funktion useLocale bereitgestellt wird. Damit können Sie die Sprache der Anwendung festlegen und den Inhalt entsprechend aktualisieren.

Erstellen Sie eine Komponente, um zwischen den Sprachen zu wechseln:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

Nutzen Sie dann diese Komponente in Ihrer app.component.ts:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

TypeScript konfigurieren

Intlayer verwendet Modulerweiterung (Module Augmentation), um die Vorteile von TypeScript zu nutzen und Ihre Codebasis sicherer zu machen.

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

{  // ... Ihre vorhandenen TypeScript-Konfigurationen  "include": [    // ... Ihre vorhandenen TypeScript-Konfigurationen    ".intlayer/**/*.ts", // Automatisch generierte Typen einschließen  ],}

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dadurch wird verhindert, dass sie in Ihr Git-Repository übertragen werden.

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

# Dateien ignorieren, die von Intlayer generiert wurden.intlayer

VS Code-Erweiterung

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

Aus dem VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen von übersetzten Inhalten.
• Schnellaktionen zur einfachen Erstellung und Aktualisierung von Übersetzungen.

Weitere Informationen zur Nutzung der Erweiterung finden Sie in der Dokumentation der Intlayer VS Code Extension.

Weiter gehen

Um noch weiter zu gehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mithilfe des CMS auslagern.