Dokumentation

Erstkonfiguration

Beginnen Sie damit, das Lokalisierungspaket von Angular zu Ihrem Projekt hinzuzufügen:

ng add @angular/localize

Dieser Befehl wird die folgenden Änderungen vornehmen:

  • Fügen Sie das Paket @angular/localize zu Ihren Abhängigkeiten hinzu
  • Fügen Sie „@angular/localize/init“ zum Polyfill-Array in angular.json hinzu
  • Fügen Sie die folgende Referenz zu Ihrer main.ts hinzu:
/// <reference types="@angular/localize" />

Es wird auch die extract-i18n-Konfiguration zu angular.json hinzugefügt:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Hinweis: Wir werden den outputPath später in der Konfiguration ändern, um ihn an unseren Arbeitsablauf anzupassen.

Angular i18n CLI Tool

To simplify the management of Angular i18n configuration, you can use our CLI tool:

npm install --save-dev @softwarity/angular-i18n-cli

This tool provides several features to streamline your i18n workflow:

  • Easy initialization of i18n configuration in your Angular project
  • Simple addition and removal of locales
  • Automatic configuration of build settings for each locale
  • Proper setup of XLIFF file formats

Angular i18n CLI

CLI tool to simplify Angular i18n configuration and locale management.

Installationswerkzeug für Übersetzungen

Um Übersetzungsdateien zu verwalten, verwenden wir ng-extract-i18n-merge, das den Prozess des Extrahierens und Zusammenführens von Übersetzungen vereinfacht:

npm install --save-dev ng-extract-i18n-merge

Dieses Tool bietet mehrere Vorteile:

  • Automatisch übersetzt, was von Ihrer Anwendung übersetzbar ist
  • Fügt neue Übersetzungen in einem einzigen Schritt mit bestehenden zusammen
  • Beibehält bestehende Übersetzungen während Updates
  • Unterstützt mehrere Zielsprache

Konfigurationsdateien

package.json

"scripts": {
  ...
  "extract-i18n": "ng extract-i18n",
  "build": "ng build --localize"
  ...
}

angular.json

Aktualisieren Sie die i18n-Konfiguration in angular.json:

"i18n": {
  "sourceLocale": "en",
  "locales": {
    "fr": {
      "translation": "src/locale/messages.fr.xlf"
    },
    "vi": {
      "translation": "src/locale/messages.vi.xlf"
    }
  }
},

Ersetzen Sie die Standardkonfiguration für extract-i18n durch ng-extract-i18n-merge:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Wichtige Konfigurationsoptionen:

  • buildTarget: Der Name des Build-Ziels Ihrer Anwendung
  • outputPath: Verzeichnis, in dem die Übersetzungsdateien gespeichert werden
  • Kontext einbeziehen: Enthält Informationen zur Quelldatei in den XLIFF-Dateien
  • Übersetzungsstatus zurücksetzen: Kennzeichnet alle Übersetzungen als überprüfungsbedürftig bei Änderungen
  • Ziel-Dateien: Liste der zu generierenden/aktualisierenden Übersetzungsdateien

Build configurations

Fügen Sie Konfigurationen für jede Sprache im Build-Bereich hinzu:

"architect": {
  "build": {
    "configurations": {
      "fr": {
        "localize": ["fr"]
      },
      "vi": {
        "localize": ["vi"]
      }
    }
  }
}

Bereiten Sie Komponenten für die Übersetzung vor

Um Ihre Komponenten für die Übersetzung vorzubereiten, müssen Sie den Text markieren, der übersetzt werden soll. Angular bietet zwei Möglichkeiten, dies zu tun:

Angular-Dokumentation: Text für Übersetzungen markieren

Erfahren Sie mehr darüber, wie Sie Ihre Anwendung für die Übersetzung vorbereiten können.

Vorlagenübersetzung

Verwenden Sie das i18n-Attribut in Ihren Vorlagen, um Text für die Übersetzung zu kennzeichnen:

<tag attribute="This is a sample attribute text that needs translation." 
  i18n-attribute="@@ATTRIBUTE_TEXT"
  i18n="@@TAG_TEXT">This is a sample text that needs translation.</tag>
// EXAMPLE
<button title="Title button" i18n-title="@@TITLE_BUTTON"i18n="@@LABEL_BUTTON">label button</button>

Das @@prefix definiert eine benutzerdefinierte ID für die Übersetzung. Es wird empfohlen, SNAKE_CASE für Konsistenz zu verwenden.

Komponentenübersetzung

Verwenden Sie für den Text in Ihrem Komponenten-Code das $localize-Template-Tag:

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: '...'
})
export class ExampleComponent {
  title = $localize`:@@PAGE_TITLE:Welcome to our application`;
  errorMessage = $localize`:@@ERROR_MESSAGE:An error occurred while processing your request`;
}

Bauen und Bereitstellen

Bauen mit Übersetzungen

Bauen Sie Ihre Anwendung mit allen Übersetzungen:

npm run build

Oder für eine spezifische Sprache zu bauen (unter Verwendung von Französisch als Beispiel):

ng build --configuration=fr

Entwicklungsserver

Liefern Sie Ihre Anwendung während der Entwicklung mit Übersetzungen aus:

ng serve --configuration=fr

⚠️ Wichtige Anmerkung

Nachdem Sie neue übersetzbare Inhalte hinzugefügt oder bestehende Übersetzungen geändert haben:

  1. ng extract-i18n - um alle Übersetzungsdateien in einem Schritt zu extrahieren und zu aktualisieren

Dieser vereinfachte Arbeitsablauf sorgt dafür, dass Ihre Übersetzungsdateien immer mit dem Quellinhalt auf dem neuesten Stand sind, was den Internationalisierungsprozess effizienter und fehlerfreier macht.