Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App

Von Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana, und Hisham Bin Ateya

Eine Aufgabe bei der Lokalisierung einer App besteht darin, lokalisierte Strings in Ressourcendateien bereitzustellen. In diesem Artikel geht es um das Arbeiten mit Ressourcendateien.

SupportedCultures und SupportedUICultures

ASP.NET Core verfügt über zwei Auflistungen von Kulturwerten: SupportedCultures und SupportedUICultures. Das Objekt CultureInfo für SupportedCultures bestimmt die Ergebnisse von kulturabhängigen Funktionen, wie z.B. das Format von Datumswerten, Uhrzeiten, Zahlen und Währungen. SupportedCultures bestimmt auch die Sortierreihenfolge von Texten, Groß-/Kleinschreibungskonventionen und Zeichenfolgenvergleichen. Weitere Informationen darüber, wie der Server die Kultur abruft, finden Sie unter StringComparer.CurrentCulture. SupportedUICultures bestimmt, welche übersetzten Zeichenfolgen (aus den RESX-Dateien) von ResourceManager abgerufen werden. Die ResourceManager-Klasse sucht nach kulturspezifischen Zeichenfolgen, die durch CurrentUICulture bestimmt werden. Jeder Thread in .NET enthält die Objekte CurrentCulture und CurrentUICulture. ASP.NET Core überprüft diese Werte beim Rendern von kulturspezifischen Funktionen. Wenn die Kultur des aktuellen Threads zum Beispiel auf „en-US“ (Englisch, USA) festgelegt ist, gibt DateTime.Now.ToLongDateString() „Thursday, February 18, 2016“ aus, wenn CurrentCulture jedoch auf „es-ES“ (Spanisch, Spanien) festgelegt ist, wird „jueves, 18 de febrero de 2016“ ausgegeben.

Ressourcendateien

HINWEIS: ResX Viewer and Editor ist eine Alternative zur Arbeit mit Ressourcendateien in Visual Studio Code.

Eine Ressourcendatei ist ein nützlicher Mechanismus für das Trennen von lokalisierbaren Zeichenfolgen von Code. Übersetzte Zeichenfolgen für die Sprache, die nicht die Standardsprache darstellt, werden in RESX-Ressourcendateien isoliert. Möglicherweise möchten Sie z.B. eine spanische Ressourcendatei namens Welcome.es.resx erstellen, die übersetzte Zeichenfolgen enthält. „es“ ist der Sprachcode für Spanisch. Erstellen dieser Ressourcendatei in Visual Studio:

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Ordner, der die Ressourcendatei enthalten soll, und wählen Sie dann Hinzufügen>Neues Element.

   

2. Geben Sie „resource“ (Ressource) im Feld Search installed templates (Installierte Vorlagen durchsuchen) ein, und benennen Sie die Datei.

   

3. Geben Sie den Schlüsselwert (native Zeichenfolge) in der Spalte Name und die übersetzte Zeichenfolge in der Spalte Wert ein.

   

   Die Datei Welcome.es.resx wird in Visual Studio angezeigt.

   

Benennung von Ressourcendateien

Ressourcen werden nach dem vollständigen Typnamen ihrer Klasse, abzüglich des Assemblynamens, benannt. Eine französische Ressourcendatei, deren Hauptassembly für die Klasse LocalizationWebsite.Web.StartupLocalizationWebsite.Web.dll ist, würde zum Beispiel den Namen Startup.fr.resx erhalten. Eine Ressource für die Klasse LocalizationWebsite.Web.Controllers.HomeController würde den Namen Controllers.HomeController.fr.resx erhalten. Wenn der Namespace Ihrer Zielklasse nicht dem Assemblynamen entspricht, benötigen Sie den vollständigen Typnamen. Eine Ressource für den Typ ExtraNamespace.Tools im Beispielprojekt würde z.B. den Namen ExtraNamespace.Tools.fr.resx erhalten.

Im Beispielprojekt legt die Methode ConfigureServices die Eigenschaft ResourcesPath auf „Ressourcen“ fest. Der relative Projektpfad für den home-Controller der französischen Ressourcendatei lautet also Resources/Controllers.HomeController.fr.resx. Alternativ können Sie Ordner zum Organisieren von Ressourcendateien verwenden. Für den home-Controller würde der Pfad Resources/Controllers/HomeController.fr.resx lauten. Wenn Sie die Option ResourcesPath nicht verwenden, würde sich die RESX-Datei im Basisprojektverzeichnis befinden. Die Ressourcendatei für HomeController würde den Namen Controllers.HomeController.fr.resx erhalten. Ob Sie die Benennungskonventionen mit Punkten oder wie Pfade verwenden, hängt davon ab, wie Sie Ihre Ressourcendateien organisieren möchten.

Ressourcenname	Punkt- oder Pfadbenennung
Resources/Controllers.HomeController.fr.resx	Punkt
Resources/Controllers/HomeController.fr.resx	Pfad

Ressourcendateien, die @inject IViewLocalizer in Razor-Ansichten verwenden, folgen einem ähnlichen Muster. Die Ressourcendatei für eine Ansicht kann mit der Punkt- oder Pfadbenennung benannt werden. Ressourcendateien der Razor-Ansicht imitieren den Pfad ihrer zugehörigen Ansichtsdatei. Wenn ResourcesPath zum Beispiel auf „Resources“ festgelegt wird, ist die Ressourcendatei für Französisch, die der Ansicht Views/Home/About.cshtml zugeordnet ist, eine der folgenden beiden:

• Resources/Views/Home/About.fr.resx

• Resources/Views.Home.About.fr.resx

Wenn Sie nicht die Option ResourcesPath verwenden, befindet sich die RESX-Datei für eine Ansicht im selben Ordner wie die Ansicht.

RootNamespaceAttribute

Das RootNamespaceAttribute-Attribut stellt den Stammnamespace einer Assembly bereit, wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet.

Warnung

Dies kann vorkommen, wenn der Name eines Projekts kein gültiger .NET-Bezeichner ist. Beispielsweise verwendet my-project-name.csproj den Stammnamespace my_project_name und den Assemblynamen my-project-name, der zu diesem Fehler führt.

Wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet, dann geschieht Folgendes:

• Die Lokalisierung funktioniert standardmäßig nicht.
• Die Lokalisierung schlägt aufgrund der Art und Weise, wie nach Ressourcen innerhalb der Assembly gesucht wird, fehl. RootNamespace ist ein Buildzeitwert, der für den ausgeführten Prozess nicht verfügbar ist.

Wenn sich RootNamespace vom AssemblyName unterscheidet, schließen Sie Folgendes in AssemblyInfo.cs ein (mit den durch die aktuellen Werte ersetzten Parameterwerten):

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

Der vorangehende Code ermöglicht die erfolgreiche Auflösung von RESX-Dateien.

Kulturfallbackverhalten

Bei der Suche nach einer Ressource initiiert die Lokalisierung „Kulturfallbackverhalten“. Wenn die angeforderte Kultur nicht gefunden wird, setzt sie diese Kultur auf die übergeordnete Kultur zurück. Die Eigenschaft CultureInfo.Parent stellt übrigens die übergeordnete Kultur dar. Dies bedeutet in der Regel (aber nicht immer), dass der nationale Bezeichner aus dem Sprach- und Kulturcode entfernt wird. Beispielsweise ist der in Mexiko gesprochene spanische Sprache „es-MX“. Das übergeordnete Element „es“ (Spanisch) ist nicht länderspezifisch.

Nehmen Sie an, dass Ihre Website eine Anforderung für eine Willkommensressource mit der Kultur „fr-CA“ erhält. Das Lokalisierungssystem sucht der Reihenfolge nach nach der folgenden Ressource und wählt die erste Übereinstimmung aus:

• Welcome.fr-CA.resx
• Welcome.fr.resx
• Welcome.resx (wenn NeutralResourcesLanguage „fr-CA“ ist)

Wenn Sie beispielsweise den Kulturkennzeichner „.fr“ entfernen und die Kultur auf „Französisch“ festgelegt ist, wird die Standardressourcendatei gelesen, und Zeichenfolgen werden lokalisiert. Der Ressourcen-Manager kennzeichnet eine Standard- oder Fallbackressource, wenn keine Entsprechung für die angeforderte Kultur gefunden wird. Wenn Sie nur den Schlüssel zurückgeben möchten, während eine Ressource für die angefragte Kultur fehlt, darf keine Standardressourcendatei festgelegt sein.

Erstellen von Ressourcendateien mit Visual Studio

Wenn Sie eine Ressourcendatei in Visual Studio erstellen, ohne eine Kultur im Dateinamen (z.B. Welcome.resx) festzulegen, erstellt Visual Studio eine C#-Klasse mit einer Eigenschaft für jede Zeichenfolge. Das ist in der Regel nicht das, was Sie mit ASP.NET Core erreichen wollen. In der Regel gibt es keine Standard-RESX-Ressourcendatei (eine RESX-Datei ohne den Kulturnamen). Es wird empfohlen, dass Sie eine RESX-Datei mit einem Kulturnamen erstellen (z.B. Welcome.fr.resx). Wenn Sie eine RESX-Datei mit einem Kulturnamen erstellen, erstellt Visual Studio keine Klassendatei.

Hinzufügen von anderen Kulturen

Jede Kombination von Sprache und Kultur (mit Ausnahme der Standardsprache) erfordert eine eindeutige Ressourcendatei. Sie erstellen Ressourcendateien für verschiedene Kulturen und Gebietsschemas, indem Sie neue Ressourcendateien erstellen, in denen Sprachcodes im Dateinamen enthalten sind (z. B. en-usfr-ca, und en-gb). Diese Codes werden zwischen dem Dateinamen und der Erweiterung .resx platziert, z. B. Welcome.es-MX.resx (Spanisch/Mexiko).

Nächste Schritte

Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:

• Den Inhalt der App lokalisierbar machen.
• Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.

Zusätzliche Ressourcen

• URL-Kulturanbieter, der Middleware als Filter in ASP.NET Core verwendet
• Globales Anwenden von RouteDataRequest CultureProvider mit Middleware als Filter
• Globalisierung und Lokalisierung in ASP.NET Core
• Den Inhalt einer ASP.NET Core-App lokalisierbar machen
• Strategien zur Auswahl von Sprache und Kultur in einer lokalisierten ASP.NET Core-App
• Problembehandlung bei der ASP.NET Core-Lokalisierung
• Globalisieren und Lokalisieren von .NET-Anwendungen
• Localization.StarterWeb-Projekt wird im Artikel verwendet.
• Ressourcen in RESX-Dateien
• Microsoft Multilingual App Toolkit
• Lokalisierung und Generics