Freigeben über

Konfigurieren der Lokalisierung portabler Objekte in ASP.NET Core

  • Artikel

Von Hisham Bin Ateya und Sébastien Ros.

Dieser Artikel erläutert die Schritte zur Verwendung von portablen Objektdateien (PO) in einer ASP.NET Core-Anwendung mit dem Framework Orchard Core.

Hinweis: Orchard Core ist kein Microsoft-Produkt. Microsoft bietet keinen Support für dieses Feature an.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Was ist eine PO-Datei?

PO-Dateien werden als Textdateien verteilt, die übersetzte Zeichenfolgen für eine bestimmte Sprache enthalten. Einige Vorteile der Verwendung von PO-Dateien im Vergleich zu RESX-Dateien sind:

  • PO-Dateien unterstützen Pluralisierung; RESX-Dateien unterstützen sie nicht.
  • PO-Dateien werden nicht wie RESX-Dateien kompiliert. Daher sind spezialisierte Tools und die Buildschritte nicht erforderlich.
  • PO-Dateien funktionieren gut mit gemeinsamen Onlinebearbeitungstools.

Beispiel

Nachfolgend sehen Sie eine PO-Beispieldatei, die die Übersetzung für zwei Zeichenfolgen in Französisch enthält, einschließlich der Pluralform einer der Zeichenfolgen:

fr.po

#: Pages/Index.cshtml:13
msgid "Hello world!"
msgstr "Bonjour le monde!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

In diesem Beispiel wird die folgende Syntax verwendet:

  • #:: ein Kommentar, der den Kontext der zu übersetzenden Zeichenfolge angibt. Die gleiche Zeichenfolge wird möglicherweise anders übersetzt, je nachdem, wo sie verwendet wird.
  • msgid: die nicht übersetzte Zeichenfolge.
  • msgstr: die übersetzte Zeichenfolge.

Für die Pluralisierung können mehrere Einträge definiert werden.

  • msgid_plural: die nicht übersetzte Zeichenfolge im Plural.
  • msgstr[0]: die übersetzte Zeichenfolge für den Fall 0.
  • msgstr[N]: die übersetzte Zeichenfolge für den Fall N.

Die PO-Dateispezifikation finden Sie hier.

Konfigurieren der PO-Dateiunterstützung in ASP.NET Core

Dieses Beispiel beruht auf einer ASP.NET Core-Webanwendung, die aus einer Visual Studio 2022-Projektvorlage generiert wurde.

Verweisen auf das Paket

Fügen Sie einen Verweis auf das NuGet-Paket OrchardCore.Localization.Core hinzu.

Die .csproj-Datei enthält nun eine Zeile, die der folgenden Zeile ähnelt (die Versionsnummer kann davon abweichen):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.5.0" />

Registrieren des Diensts

Fügen Sie die erforderlichen Dienste zu Program.cs hinzu:

builder.Services.AddPortableObjectLocalization();

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

builder.Services
    .AddRazorPages()
    .AddViewLocalization();

Fügen Sie den folgenden Code zur Razor-Seite Ihrer Wahl hinzu. In diesem Beispiel wird Index.cshtml verwendet.

@page
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
    ViewData["Title"] = "Home";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
</div>

<p>@Localizer["Hello world!"]</p>

Eine IViewLocalizer-Instanz wird eingefügt und zum Übersetzen des Texts „Hello world!“ verwendet.

Erstellen einer PO-Datei

Erstellen Sie eine Datei mit dem Namen <Kulturcode>.po im Stammordner Ihrer Anwendung. In diesem Beispiel lautet der Dateiname fr.po, weil die französische Sprache verwendet wird:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Diese Datei speichert die zu übersetzende Zeichenfolge sowie die französische Zeichenfolge. Übersetzungen stellen ihre übergeordnete Kultur wieder her, wenn erforderlich. In diesem Beispiel wird die fr.po-Datei verwendet, wenn die angeforderte Kultur fr-FR oder fr-CA ist.

Testen der Anwendung

Führen Sie Ihre Anwendung aus, und der Text Hello world! wird angezeigt.

Navigieren Sie zur URL /Index?culture=fr-FR. Der Text Bonjour le monde! wird angezeigt.

Pluralisierung

PO-Dateien unterstützen Pluralformen. Dies ist nützlich, wenn die gleiche Zeichenfolge aufgrund einer Kardinalität unterschiedlich übersetzt werden muss. Diese Aufgabe ist komplizierter, da jede Sprache benutzerdefinierte Regeln festlegt, um auf der Grundlage von Kardinalität auszuwählen, welche Zeichenfolge zu verwenden ist.

Das Orchard Localization-Paket stellt eine API zur Verfügung, um diese anderen Pluralformen automatisch aufzurufen.

Erstellen von PO-Pluraldateien

Fügen Sie den folgenden Inhalt zur zuvor erwähnten fr.po-Datei hinzu:

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Unter Was ist eine PO-Datei? finden Sie eine Erläuterung für das, was jeder Eintrag in diesem Beispiel darstellt.

Hinzufügen einer Sprache mit verschiedenen Pluralformen

Im vorherigen Beispiel wurden englische und französische Zeichenfolgen verwendet. Englisch und Französisch haben nur zwei Pluralformen und teilen die gleichen Formregeln. Die Kardinalität der einen wird der ersten Pluralform zugeordnet. Alle anderen Kardinalitäten werden der zweiten Pluralform zugeordnet.

Nicht alle Sprachen verfügen über die gleichen Regeln. Tschechisch verfügt beispielsweise über drei Pluralformen.

Erstellen Sie die cs.po-Datei wie folgt, und beachten Sie die drei verschiedenen Übersetzungen der Pluralformen:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Fügen Sie für die Annahme der tschechischen Lokalisierungen "cs" zur Liste der unterstützten Kulturen in der Configure-Methode hinzu:

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

Bearbeiten Sie die Datei Pages/Index.cshtml, um lokalisierte Pluralzeichenfolgen für mehrere Kardinalitäten zu rendern:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Hinweis: In einem echten Szenario würde eine Variable die Anzahl darstellen. Hier wiederholen wir den gleichen Code mit drei verschiedenen Werten, um einen speziellen Fall verfügbar zu machen.

Beim Wechsel von Kulturen sehen Sie Folgendes:

Für /Index:

There is one item.
There are 2 items.
There are 5 items.

Für /Index?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

Für /Index?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Die drei Übersetzungen sind für die tschechische Kultur unterschiedlich. Die französische und englische Kultur teilen die gleiche Konstruktion für die beiden letzten übersetzten Zeichenfolgen.

Aufgaben für Fortgeschrittene

Verwenden zusätzlicher Argumente

Das Argument bei Index 0 {0} stellt immer den Zählwert dar. Beim Aufrufen der Plural-Methode ist es möglich, zusätzliche Argumente hinzuzufügen. Ihr Index beginnt dann bei Eins (1).

<p>@Localizer.Plural(count, "There is one item with the color {1}.", "There are {0} items. The main color is {1}.", color)</p>

Kontextualisieren von Zeichenfolgen

Anwendungen enthalten die zu übersetzenden Zeichenfolgen häufig an mehreren Stellen. Dieselbe Zeichenfolge kann möglicherweise über unterschiedliche Übersetzungen in bestimmten Speicherorten innerhalb einer Anwendung verfügen (Razor-Ansichten oder Klassendateien). Eine PO-Datei unterstützt das Konzept eines Dateikontexts, der zum Kategorisieren von dargestellten Zeichenfolgen verwendet werden kann. Bei der Verwendung eines Dateikontexts kann eine Zeichenfolge unterschiedlich übersetzt werden. Dies hängt vom Dateikontext (oder einem fehlenden Dateikontext) ab.

Die PO-Lokalisierungsdienste verwenden den Namen der vollständigen Klasse oder der Ansicht, die bei der Übersetzung einer Zeichenfolge verwendet wird. Dies wird durch Festlegen des Werts im msgctxt-Eintrag erreicht.

Ziehen Sie eine geringfügige Hinzufügung zum vorherigen fr.po-Beispiel in Erwägung. Sie können eine Razor-Seite unter Pages/Index.cshtml als Dateikontext definieren, indem Sie den reservierten Wert des msgctxt-Eintrags festlegen:

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Wenn msgctxt festgelegt ist, wird bei der Navigation zu /Index?culture=fr-FR eine Textübersetzung ausgeführt. Die Übersetzung wird nicht bei der Navigation zu /Privacy?culture=fr-FR ausgeführt.

Wenn kein bestimmter Eintrag mit einem bestimmten Dateikontext abgeglichen wird, sucht der Fallbackmechanismus von Orchard Core nach einer entsprechenden PO-Datei ohne Kontext. Sofern kein spezifischer Dateikontext für Pages/Privacy.cshtml definiert wurde, wird durch Navigation zu /Privacy?culture=fr-FR eine PO-Datei geladen, z. B.:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ändern des Speicherorts für PO-Dateien

Der Standardspeicherort der PO-Dateien kann in Programs.cs geändert werden:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

In diesem Beispiel werden die PO-Dateien aus dem Ordner Lokalisierung geladen.

Implementieren einer benutzerdefinierten Logik für die Suche nach Lokalisierungsdateien

Wenn eine komplexere Logik erforderlich ist, um die PO-Dateien zu finden, kann die OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider-Schnittstelle implementiert und als Dienst registriert werden. Dies ist nützlich, wenn PO-Dateien an unterschiedlichen Speicherorten gespeichert oder die Dateien innerhalb einer Hierarchie von Ordnern gefunden werden können.

Verwenden einer anderen Standardpluralsprache

Das Paket enthält eine Plural-Erweiterungsmethode, die für zwei Pluralformen spezifisch ist. Erstellen Sie eine Erweiterungsmethode für Sprachen, die weitere Pluralformen erfordern. Mit einer Erweiterungsmethode müssen Sie keine Lokalisierungsdatei für die Standardsprache angeben – die ursprünglichen Zeichenfolgen sind bereits direkt im Code verfügbar.

Sie können die generische Plural(int count, string[] pluralForms, params object[] arguments)-Überladung verwenden, die ein Zeichenfolgenarray von Übersetzungen akzeptiert.

Von Sébastien Ros, Scott Addie und Hisham Bin Ateya

Dieser Artikel erläutert die Schritte zur Verwendung von portablen Objektdateien (PO) in einer ASP.NET Core-Anwendung mit dem Framework Orchard Core.

Hinweis: Orchard Core ist kein Microsoft-Produkt. Microsoft bietet daher keinen Support für dieses Feature an.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Was ist eine PO-Datei?

PO-Dateien werden als Textdateien verteilt, die übersetzte Zeichenfolgen für eine bestimmte Sprache enthalten. Einige Vorteile der Verwendung von PO-Dateien im Vergleich zu RESX-Dateien sind:

  • PO-Dateien unterstützen Pluralisierung; RESX-Dateien unterstützen sie nicht.
  • PO-Dateien werden nicht wie RESX-Dateien kompiliert. Daher sind spezialisierte Tools und die Buildschritte nicht erforderlich.
  • PO-Dateien funktionieren gut mit gemeinsamen Onlinebearbeitungstools.

Beispiel

Hier sehen Sie eine PO-Beispieldatei, die die Übersetzung für zwei Zeichenfolgen in Französisch, einschließlich der Pluralform einer der Zeichenfolgen enthält:

fr.po

#: Pages/Index.cshtml:13
msgid "Hello world!"
msgstr "Bonjour le monde!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

In diesem Beispiel wird die folgende Syntax verwendet:

  • #:: ein Kommentar, der den Kontext der zu übersetzenden Zeichenfolge angibt. Die gleiche Zeichenfolge wird möglicherweise anders übersetzt, je nachdem, wo sie verwendet wird.
  • msgid: die nicht übersetzte Zeichenfolge.
  • msgstr: die übersetzte Zeichenfolge.

Wenn die Pluralisierung unterstützt wird, können mehrere Einträge definiert werden.

  • msgid_plural: die nicht übersetzte Zeichenfolge im Plural.
  • msgstr[0]: die übersetzte Zeichenfolge für den Fall 0.
  • msgstr[N]: die übersetzte Zeichenfolge für den Fall N.

Die PO-Dateispezifikation finden Sie hier.

Konfigurieren der PO-Dateiunterstützung in ASP.NET Core

Dieses Beispiel beruht auf einer ASP.NET Core MVC-Anwendung, die aus einer Visual Studio 2019-Projektvorlage generiert wurde.

Verweisen auf das Paket

Fügen Sie einen Verweis auf das NuGet-Paket OrchardCore.Localization.Core hinzu.

Die .csproj-Datei enthält nun eine Zeile, die der folgenden Zeile ähnelt (die Versionsnummer kann davon abweichen):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.2.0" />

Registrieren des Diensts

Fügen Sie die erforderlichen Dienste zur ConfigureServices-Methode von Startup.cs hinzu:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

    services.AddPortableObjectLocalization();

    services.Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs")
    );
}

Fügen Sie die erforderliche Middleware zur Configure-Methode von Startup.cs hinzu:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseRouting();
    app.UseStaticFiles();

    app.UseRequestLocalization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Fügen Sie den folgenden Code zur Razor-Seite Ihrer Wahl hinzu. In diesem Beispiel wird Index.cshtml verwendet.

@page
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
    ViewData["Title"] = "Home";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
</div>

<p>@Localizer["Hello world!"]</p>

Eine IViewLocalizer-Instanz wird eingefügt und zum Übersetzen des Texts „Hello world!“ verwendet.

Erstellen einer PO-Datei

Erstellen Sie eine Datei mit dem Namen <Kulturcode>.po im Stammordner Ihrer Anwendung. In diesem Beispiel lautet der Dateiname fr.po, weil die französische Sprache verwendet wird:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Diese Datei speichert die zu übersetzende Zeichenfolge sowie die französische Zeichenfolge. Übersetzungen stellen ihre übergeordnete Kultur wieder her, wenn erforderlich. In diesem Beispiel wird die fr.po-Datei verwendet, wenn die angeforderte Kultur fr-FR oder fr-CA ist.

Testen der Anwendung

Führen Sie Ihre Anwendung aus, und navigieren Sie zur URL/Index. Der Text Hello world! wird angezeigt.

Navigieren Sie zur URL /Index?culture=fr-FR. Der Text Bonjour le monde! wird angezeigt.

Pluralisierung

PO-Dateien unterstützen Pluralformen. Dies ist nützlich, wenn die gleiche Zeichenfolge aufgrund einer Kardinalität unterschiedlich übersetzt werden muss. Diese Aufgabe ist komplizierter, da jede Sprache benutzerdefinierte Regeln festlegt, um auf der Grundlage von Kardinalität auszuwählen, welche Zeichenfolge zu verwenden ist.

Das Orchard Localization-Paket stellt eine API zur Verfügung, um diese anderen Pluralformen automatisch aufzurufen.

Erstellen von PO-Pluraldateien

Fügen Sie den folgenden Inhalt zur zuvor erwähnten fr.po-Datei hinzu:

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Unter Was ist eine PO-Datei? finden Sie eine Erläuterung für das, was jeder Eintrag in diesem Beispiel darstellt.

Hinzufügen einer Sprache mit verschiedenen Pluralformen

Im vorherigen Beispiel wurden englische und französische Zeichenfolgen verwendet. Englisch und Französisch haben nur zwei Pluralformen und teilen die gleichen Formregeln. Die Kardinalität der einen wird der ersten Pluralform zugeordnet. Alle anderen Kardinalitäten werden der zweiten Pluralform zugeordnet.

Nicht alle Sprachen verfügen über die gleichen Regeln. Tschechisch verfügt beispielsweise über drei Pluralformen.

Erstellen Sie die cs.po-Datei wie folgt, und beachten Sie die drei verschiedenen Übersetzungen der Pluralformen:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Fügen Sie für die Annahme der tschechischen Lokalisierungen "cs" zur Liste der unterstützten Kulturen in der ConfigureServices-Methode hinzu:

services.Configure<RequestLocalizationOptions>(options => options
                .AddSupportedCultures("fr", "cs")
                .AddSupportedUICultures("fr", "cs")
            );

Bearbeiten Sie die Datei Pages/Index.cshtml, um lokalisierte Pluralzeichenfolgen für mehrere Kardinalitäten zu rendern:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Hinweis: In einem echten Szenario würde eine Variable die Anzahl darstellen. Hier wiederholen wir den gleichen Code mit drei verschiedenen Werten, um einen sehr speziellen Fall verfügbar zu machen.

Beim Wechsel von Kulturen sehen Sie Folgendes:

Für /Index:

There is one item.
There are 2 items.
There are 5 items.

Für /Index?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

Für /Index?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Beachten Sie, dass die drei Übersetzungen für die tschechische Kultur unterschiedlich sind. Die französische und englische Kultur teilen die gleiche Konstruktion für die beiden letzten übersetzten Zeichenfolgen.

Aufgaben für Fortgeschrittene

Kontextualisieren von Zeichenfolgen

Anwendungen enthalten die zu übersetzenden Zeichenfolgen häufig an mehreren Stellen. Dieselbe Zeichenfolge kann möglicherweise über unterschiedliche Übersetzungen in bestimmten Speicherorten innerhalb einer Anwendung verfügen (Razor-Ansichten oder Klassendateien). Eine PO-Datei unterstützt das Konzept eines Dateikontexts, der zum Kategorisieren von dargestellten Zeichenfolgen verwendet werden kann. Bei der Verwendung eines Dateikontexts kann eine Zeichenfolge unterschiedlich übersetzt werden. Dies hängt vom Dateikontext (oder einem fehlenden Dateikontext) ab.

Die PO-Lokalisierungsdienste verwenden den Namen der vollständigen Klasse oder der Ansicht, die bei der Übersetzung einer Zeichenfolge verwendet wird. Dies wird durch Festlegen des Werts im msgctxt-Eintrag erreicht.

Ziehen Sie eine geringfügige Hinzufügung zum vorherigen fr.po-Beispiel in Erwägung. Sie können eine Razor-Ansicht unter Pages/Index.cshtml als Dateikontext definieren, indem Sie den reservierten Wert des msgctxt-Eintrags festlegen:

msgctxt "Pages.Index"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Wenn msgctxt festgelegt ist, wird bei der Navigation zu /Index?culture=fr-FR eine Textübersetzung ausgeführt. Die Übersetzung wird nicht bei der Navigation zu /Privacy?culture=fr-FR ausgeführt.

Wenn kein bestimmter Eintrag mit einem bestimmten Dateikontext abgeglichen wird, sucht der Fallbackmechanismus von Orchard Core nach einer entsprechenden PO-Datei ohne Kontext. Sofern kein spezifischer Dateikontext für Pages/Privacy.cshtml definiert wurde, wird durch Navigation zu /Privacy?culture=fr-FR eine PO-Datei geladen, z. B.:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ändern des Speicherorts für PO-Dateien

Der Standardspeicherort der PO-Dateien kann in ConfigureServices geändert werden:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

In diesem Beispiel werden die PO-Dateien aus dem Ordner Lokalisierung geladen.

Implementieren einer benutzerdefinierten Logik für die Suche nach Lokalisierungsdateien

Wenn eine komplexere Logik erforderlich ist, um die PO-Dateien zu finden, kann die OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider-Schnittstelle implementiert und als Dienst registriert werden. Dies ist nützlich, wenn PO-Dateien an unterschiedlichen Speicherorten gespeichert oder die Dateien innerhalb einer Hierarchie von Ordnern gefunden werden können.

Verwenden einer anderen Standardpluralsprache

Das Paket enthält eine Plural-Erweiterungsmethode, die für zwei Pluralformen spezifisch ist. Erstellen Sie eine Erweiterungsmethode für Sprachen, die weitere Pluralformen erfordern. Mit einer Erweiterungsmethode müssen Sie keine Lokalisierungsdatei für die Standardsprache angeben – die ursprünglichen Zeichenfolgen sind bereits direkt im Code verfügbar.

Sie können die generische Plural(int count, string[] pluralForms, params object[] arguments)-Überladung verwenden, die ein Zeichenfolgenarray von Übersetzungen akzeptiert.

Von Sébastien Ros, Scott Addie und Hisham Bin Ateya

Dieser Artikel erläutert die Schritte zur Verwendung von portablen Objektdateien (PO) in einer ASP.NET Core-Anwendung mit dem Framework Orchard Core.

Hinweis: Orchard Core ist kein Microsoft-Produkt. Microsoft bietet daher keinen Support für dieses Feature an.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Was ist eine PO-Datei?

PO-Dateien werden als Textdateien verteilt, die übersetzte Zeichenfolgen für eine bestimmte Sprache enthalten. Einige Vorteile der Verwendung von PO-Dateien im Vergleich zu RESX-Dateien sind:

  • PO-Dateien unterstützen Pluralisierung; RESX-Dateien unterstützen sie nicht.
  • PO-Dateien werden nicht wie RESX-Dateien kompiliert. Daher sind spezialisierte Tools und die Buildschritte nicht erforderlich.
  • PO-Dateien funktionieren gut mit gemeinsamen Onlinebearbeitungstools.

Beispiel

Hier sehen Sie eine PO-Beispieldatei, die die Übersetzung für zwei Zeichenfolgen in Französisch, einschließlich der Pluralform einer der Zeichenfolgen enthält:

fr.po

#: Services/EmailService.cs:29
msgid "Enter a comma separated list of email addresses."
msgstr "Entrez une liste d'emails séparés par une virgule."

#: Views/Email.cshtml:112
msgid "The email address is \"{0}\"."
msgid_plural "The email addresses are \"{0}\"."
msgstr[0] "L'adresse email est \"{0}\"."
msgstr[1] "Les adresses email sont \"{0}\""

In diesem Beispiel wird die folgende Syntax verwendet:

  • #:: ein Kommentar, der den Kontext der zu übersetzenden Zeichenfolge angibt. Die gleiche Zeichenfolge wird möglicherweise anders übersetzt, je nachdem, wo sie verwendet wird.
  • msgid: die nicht übersetzte Zeichenfolge.
  • msgstr: die übersetzte Zeichenfolge.

Wenn die Pluralisierung unterstützt wird, können mehrere Einträge definiert werden.

  • msgid_plural: die nicht übersetzte Zeichenfolge im Plural.
  • msgstr[0]: die übersetzte Zeichenfolge für den Fall 0.
  • msgstr[N]: die übersetzte Zeichenfolge für den Fall N.

Die PO-Dateispezifikation finden Sie hier.

Konfigurieren der PO-Dateiunterstützung in ASP.NET Core

Dieses Beispiel beruht auf einer ASP.NET Core MVC-Anwendung, die aus einer Visual Studio 2017-Projektvorlage generiert wurde.

Verweisen auf das Paket

Fügen Sie einen Verweis auf das NuGet-Paket OrchardCore.Localization.Core hinzu.

Die .csproj-Datei enthält nun eine Zeile, die der folgenden Zeile ähnelt (die Versionsnummer kann davon abweichen):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.0.0" />

Registrieren des Diensts

Fügen Sie die erforderlichen Dienste zur ConfigureServices-Methode von Startup.cs hinzu:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix);

    services.AddPortableObjectLocalization();

    services.Configure<RequestLocalizationOptions>(options =>
        {
            var supportedCultures = new List<CultureInfo>
            {
                new CultureInfo("en-US"),
                new CultureInfo("en"),
                new CultureInfo("fr-FR"),
                new CultureInfo("fr")
            };

            options.DefaultRequestCulture = new RequestCulture("en-US");
            options.SupportedCultures = supportedCultures;
            options.SupportedUICultures = supportedCultures;
        });
}

Fügen Sie die erforderliche Middleware zur Configure-Methode von Startup.cs hinzu:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }

    app.UseRouting();
    app.UseStaticFiles();

    app.UseRequestLocalization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Fügen Sie den folgenden Code zur Razor-Ansicht Ihrer Wahl hinzu. In diesem Beispiel wird About.cshtml verwendet.

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

<p>@Localizer["Hello world!"]</p>

Eine IViewLocalizer-Instanz wird eingefügt und zum Übersetzen des Texts „Hello world!“ verwendet.

Erstellen einer PO-Datei

Erstellen Sie eine Datei mit dem Namen <Kulturcode>.po im Stammordner Ihrer Anwendung. In diesem Beispiel lautet der Dateiname fr.po, weil die französische Sprache verwendet wird:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Diese Datei speichert die zu übersetzende Zeichenfolge sowie die französische Zeichenfolge. Übersetzungen stellen ihre übergeordnete Kultur wieder her, wenn erforderlich. In diesem Beispiel wird die fr.po-Datei verwendet, wenn die angeforderte Kultur fr-FR oder fr-CA ist.

Testen der Anwendung

Führen Sie Ihre Anwendung aus, und navigieren Sie zur URL/Home/About. Der Text Hello world! wird angezeigt.

Navigieren Sie zur URL /Home/About?culture=fr-FR. Der Text Bonjour le monde! wird angezeigt.

Pluralisierung

PO-Dateien unterstützen Pluralformen. Dies ist nützlich, wenn die gleiche Zeichenfolge aufgrund einer Kardinalität unterschiedlich übersetzt werden muss. Diese Aufgabe ist komplizierter, da jede Sprache benutzerdefinierte Regeln festlegt, um auf der Grundlage von Kardinalität auszuwählen, welche Zeichenfolge zu verwenden ist.

Das Orchard Localization-Paket stellt eine API zur Verfügung, um diese anderen Pluralformen automatisch aufzurufen.

Erstellen von PO-Pluraldateien

Fügen Sie den folgenden Inhalt zur zuvor erwähnten fr.po-Datei hinzu:

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Unter Was ist eine PO-Datei? finden Sie eine Erläuterung für das, was jeder Eintrag in diesem Beispiel darstellt.

Hinzufügen einer Sprache mit verschiedenen Pluralformen

Im vorherigen Beispiel wurden englische und französische Zeichenfolgen verwendet. Englisch und Französisch haben nur zwei Pluralformen und teilen die gleichen Formregeln. Die Kardinalität der einen wird der ersten Pluralform zugeordnet. Alle anderen Kardinalitäten werden der zweiten Pluralform zugeordnet.

Nicht alle Sprachen verfügen über die gleichen Regeln. Tschechisch verfügt beispielsweise über drei Pluralformen.

Erstellen Sie die cs.po-Datei wie folgt, und beachten Sie die drei verschiedenen Übersetzungen der Pluralformen:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Fügen Sie für die Annahme der tschechischen Lokalisierungen "cs" zur Liste der unterstützten Kulturen in der ConfigureServices-Methode hinzu:

var supportedCultures = new List<CultureInfo>
{
    new CultureInfo("en-US"),
    new CultureInfo("en"),
    new CultureInfo("fr-FR"),
    new CultureInfo("fr"),
    new CultureInfo("cs")
};

Bearbeiten Sie die Datei Views/Home/About.cshtml, um lokalisierte Pluralzeichenfolgen für mehrere Kardinalitäten zu rendern:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Hinweis: In einem echten Szenario würde eine Variable die Anzahl darstellen. Hier wiederholen wir den gleichen Code mit drei verschiedenen Werten, um einen sehr speziellen Fall verfügbar zu machen.

Beim Wechsel von Kulturen sehen Sie Folgendes:

Für /Home/About:

There is one item.
There are 2 items.
There are 5 items.

Für /Home/About?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

Für /Home/About?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Beachten Sie, dass die drei Übersetzungen für die tschechische Kultur unterschiedlich sind. Die französische und englische Kultur teilen die gleiche Konstruktion für die beiden letzten übersetzten Zeichenfolgen.

Aufgaben für Fortgeschrittene

Kontextualisieren von Zeichenfolgen

Anwendungen enthalten die zu übersetzenden Zeichenfolgen häufig an mehreren Stellen. Dieselbe Zeichenfolge kann möglicherweise über unterschiedliche Übersetzungen in bestimmten Speicherorten innerhalb einer Anwendung verfügen (Razor-Ansichten oder Klassendateien). Eine PO-Datei unterstützt das Konzept eines Dateikontexts, der zum Kategorisieren von dargestellten Zeichenfolgen verwendet werden kann. Bei der Verwendung eines Dateikontexts kann eine Zeichenfolge unterschiedlich übersetzt werden. Dies hängt vom Dateikontext (oder einem fehlenden Dateikontext) ab.

Die PO-Lokalisierungsdienste verwenden den Namen der vollständigen Klasse oder der Ansicht, die bei der Übersetzung einer Zeichenfolge verwendet wird. Dies wird durch Festlegen des Werts im msgctxt-Eintrag erreicht.

Ziehen Sie eine geringfügige Hinzufügung zum vorherigen fr.po-Beispiel in Erwägung. Sie können eine Razor-Ansicht unter Views/Home/About.cshtml als Dateikontext definieren, indem Sie den reservierten Wert des msgctxt-Eintrags festlegen:

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Wenn msgctxt festgelegt ist, wird bei der Navigation zu /Home/About?culture=fr-FR eine Textübersetzung ausgeführt. Die Übersetzung wird nicht bei der Navigation zu /Home/Contact?culture=fr-FR ausgeführt.

Wenn kein bestimmter Eintrag mit einem bestimmten Dateikontext abgeglichen wird, sucht der Fallbackmechanismus von Orchard Core nach einer entsprechenden PO-Datei ohne Kontext. Sofern kein spezifischer Dateikontext für Views/Home/Contact.cshtml definiert wurde, wird durch Navigation zu /Home/Contact?culture=fr-FR eine PO-Datei geladen, z. B.:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Ändern des Speicherorts für PO-Dateien

Der Standardspeicherort der PO-Dateien kann in ConfigureServices geändert werden:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

In diesem Beispiel werden die PO-Dateien aus dem Ordner Lokalisierung geladen.

Implementieren einer benutzerdefinierten Logik für die Suche nach Lokalisierungsdateien

Wenn eine komplexere Logik erforderlich ist, um die PO-Dateien zu finden, kann die OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider-Schnittstelle implementiert und als Dienst registriert werden. Dies ist nützlich, wenn PO-Dateien an unterschiedlichen Speicherorten gespeichert oder die Dateien innerhalb einer Hierarchie von Ordnern gefunden werden können.

Verwenden einer anderen Standardpluralsprache

Das Paket enthält eine Plural-Erweiterungsmethode, die für zwei Pluralformen spezifisch ist. Erstellen Sie eine Erweiterungsmethode für Sprachen, die weitere Pluralformen erfordern. Mit einer Erweiterungsmethode müssen Sie keine Lokalisierungsdatei für die Standardsprache angeben – die ursprünglichen Zeichenfolgen sind bereits direkt im Code verfügbar.

Sie können die generische Plural(int count, string[] pluralForms, params object[] arguments)-Überladung verwenden, die ein Zeichenfolgenarray von Übersetzungen akzeptiert.