Den Inhalt einer ASP.NET Core-App lokalisierbar machen

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

Eine Aufgabe zum Lokalisieren einer App besteht darin, lokalisierbare Inhalte mit Code zu umschließen, der das Ersetzen dieser Inhalte für verschiedene Kulturen erleichtert.

IStringLocalizer

IStringLocalizer und IStringLocalizer<T> wurden zur Förderung der Produktivität bei der Entwicklung von lokalisierten Apps entwickelt. IStringLocalizer verwendet ResourceManager und ResourceReader, um kulturspezifische Ressourcen zur Laufzeit bereitzustellen. Die Schnittstelle besitzt einen Indexer und IEnumerable für die Rückgabe von lokalisierten Zeichenfolgen. IStringLocalizer erfordert nicht, dass die Zeichenfolgen der Standardsprache in einer Ressourcendatei gespeichert werden. Sie können eine App entwickeln, die für die Lokalisierung ausgelegt ist, und müssen in den frühen Entwicklungsphasen keine Ressourcendateien erstellen.

Im folgenden Codebeispiel wird dargestellt, wie die Zeichenfolge „About Title“ für die Lokalisierung umschlossen wird.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace Localization.Controllers;

[Route("api/[controller]")]
public class AboutController : Controller
{
    private readonly IStringLocalizer<AboutController> _localizer;

    public AboutController(IStringLocalizer<AboutController> localizer)
    {
        _localizer = localizer;
    }

    [HttpGet]
    public string Get()
    {
        return _localizer["About Title"];
    }
}

Im vorangehenden Codebeispiel stammt die Implementierung von IStringLocalizer<T> aus Dependency Injection. Wenn kein lokalisierter Wert von „About Title“ gefunden wird, wird der Indexerschlüssel zurückgegeben, d.h. die Zeichenfolge „About Title“.

Sie können die Literalzeichenfolgen der App in der Standardsprache beibehalten und diese in der Lokalisierung umschließen, damit Sie sich auf die Entwicklung der App konzentrieren können. Entwickeln Sie eine App in Ihrer Standardsprache, und bereiten Sie sie auf die Lokalisierung vor, ohne zuerst eine Standardressourcendatei zu erstellen.

Alternativ können Sie das herkömmliche Verfahren verwenden und einen Schlüssel zum Abrufen der Zeichenfolge in der Standardsprache angeben. Der neue Workflow, der keine Standardsprache in der RESX-Datei verwendet und die Literalzeichenfolgen einfach umschließt, kann für viele Entwickler den Aufwand beim Lokalisieren einer App reduzieren. Andere Entwickler bevorzugen weiterhin den herkömmlichen Workflow, weil es dabei einfacher ist, mit längeren Literalzeichenfolgen zu arbeiten und lokalisierte Zeichenfolgen zu aktualisieren.

IHtmlLocalizer

Verwenden Sie die Implementierung von IHtmlLocalizer<TResource> für Ressourcen, die HTML enthalten. Mit IHtmlLocalizer werden Argumente HTML-codiert, die in der Ressourcenzeichenfolge formatiert sind. Die Ressourcenzeichenfolgen selbst werden jedoch nicht HTML-codiert. Im folgenden hervorgehobenen Code ist nur der Wert des name-Parameters HTML-codiert.

using System;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Localization;

namespace Localization.Controllers;

public class BookController : Controller
{
    private readonly IHtmlLocalizer<BookController> _localizer;

    public BookController(IHtmlLocalizer<BookController> localizer)
    {
        _localizer = localizer;
    }

    public IActionResult Hello(string name)
    {
        ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];

        return View();
    }

HINWEIS: Im Allgemeinen wird nur Text lokalisiert, nicht HTML.

IStringLocalizerFactory

Auf der niedrigsten Ebene kann IStringLocalizerFactory von Dependency Injection abgerufen werden:

public class TestController : Controller
{
    private readonly IStringLocalizer _localizer;
    private readonly IStringLocalizer _localizer2;

    public TestController(IStringLocalizerFactory factory)
    {
        var type = typeof(SharedResource);
        var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
        _localizer = factory.Create(type);
        _localizer2 = factory.Create("SharedResource", assemblyName.Name);
    }       

    public IActionResult About()
    {
        ViewData["Message"] = _localizer["Your application description page."] 
            + " loc 2: " + _localizer2["Your application description page."];

        return View();
    }

Der vorstehende Code veranschaulicht jede der beiden Methoden zum Erstellen einer Factory.

Gemeinsame Ressourcen

Sie können Ihre lokalisierten Zeichenfolgen nach Controller oder Bereich aufteilen oder nur einen Container verwenden. In der Beispiel-App wird eine Markerklasse namens SharedResource für freigegebene Ressourcen verwendet. Die Markerklasse wird nie aufgerufen:

// Dummy class to group shared resources

namespace Localization;

public class SharedResource
{
}

Im folgenden Beispiel werden die Lokalisierer InfoController und SharedResource verwendet:

public class InfoController : Controller
{
    private readonly IStringLocalizer<InfoController> _localizer;
    private readonly IStringLocalizer<SharedResource> _sharedLocalizer;

    public InfoController(IStringLocalizer<InfoController> localizer,
                   IStringLocalizer<SharedResource> sharedLocalizer)
    {
        _localizer = localizer;
        _sharedLocalizer = sharedLocalizer;
    }

    public string TestLoc()
    {
        string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
                     " Info resx " + _localizer["Hello!"];
        return msg;
    }

Lokalisierung der Ansicht

Der Dienst IViewLocalizer gibt lokalisierte Zeichenfolgen für eine Ansicht an. Die Klasse ViewLocalizer implementiert diese Schnittstelle und sucht den Speicherort der Ressource über den Dateipfad der Ansicht. Im folgenden Codebeispiel wird die Verwendung der Standardimplementierung von IViewLocalizer veranschaulicht:

@using Microsoft.AspNetCore.Mvc.Localization

@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p>@Localizer["Use this area to provide additional information."]</p>

Die Standardimplementierung von IViewLocalizer sucht die Ressourcendatei über den Dateinamen der Ansicht. Es gibt keine Option zur Nutzung einer globalen freigegebenen Ressourcendatei. ViewLocalizer implementiert den Lokalisierer mithilfe von IHtmlLocalizer, damit Razor die lokalisierte Zeichenfolge nicht HTML-codiert. Sie können Ressourcenzeichenfolgen parametrisieren, und IViewLocalizer codiert die Parameter mit HTML, aber nicht die Ressourcenzeichenfolgen. Sehen Sie sich das folgende Razor-Markup an:

@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]

Eine französische Ressourcendatei könnte folgende Werte beinhalten:

Schlüssel	Wert
<i>Hello</i> <b>{0}!</b>	<i>Bonjour</i> <b>{0} !</b>

Die gerenderte Ansicht würde das HTML-Markup der Ressourcendatei enthalten.

Im Allgemeinen wird nur Text lokalisiert, nicht HTML.

Fügen Sie IHtmlLocalizer<T> ein, um eine freigegebene Ressourcendatei in einer Ansicht zu verwenden:

@using Microsoft.AspNetCore.Mvc.Localization
@using Localization.Services

@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedLocalizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>

<h1>@SharedLocalizer["Hello!"]</h1>

Lokalisierung von DataAnnotations

Fehlermeldungen über DataAnnotations werden mit IStringLocalizer<T> lokalisiert. Durch Verwendung der Option ResourcesPath = "Resources" können die Fehlermeldungen in RegisterViewModel unter einem der folgenden Pfade gespeichert werden:

• Resources/ViewModels.Account.RegisterViewModel.fr.resx
• Resources/ViewModels/Account/RegisterViewModel.fr.resx

using System.ComponentModel.DataAnnotations;

namespace Localization.ViewModels.Account;

public class RegisterViewModel
{
    [Required(ErrorMessage = "The Email field is required.")]
    [EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
    [Display(Name = "Email")]
    public string Email { get; set; }

    [Required(ErrorMessage = "The Password field is required.")]
    [StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.",
                                                                 MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
    public string Password { get; set; }

    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage =
                            "The password and confirmation password do not match.")]
    public string ConfirmPassword { get; set; }
}

Nichtvalidierungsattribute werden lokalisiert.

Verwenden einer Ressourcenzeichenfolge für mehrere Klassen

Das folgende Codebeispiel zeigt, wie eine Ressourcenzeichenfolge für Validierungsattribute mit mehreren Klassen verwendet wird:

    services.AddMvc()
        .AddDataAnnotationsLocalization(options => {
            options.DataAnnotationLocalizerProvider = (type, factory) =>
                factory.Create(typeof(SharedResource));
        });

Im obigen Codebeispiel bezeichnet SharedResource die Klasse, die der RESX-Datei entspricht, in der die Validierungsmeldungen gespeichert sind. DataAnnotations verwendet bei diesem Ansatz nur SharedResource anstelle der Ressource für jede Klasse.

Konfigurieren von Lokalisierungsdiensten

Lokalisierungsdienste werden in Program.cs konfiguriert:

builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();

• AddLocalization fügt dem Dienstcontainer die Lokalisierungsdienste hinzu, einschließlich Implementierungen für IStringLocalizer<T> und IStringLocalizerFactory. Im vorangehenden Code wird der Ressourcenpfad auf „Resources“ festgelegt.

• AddViewLocalization fügt Unterstützung für lokalisierte Ansichtsdateien hinzu. In diesem Beispiel basiert die Lokalisierung der Ansicht auf dem Suffix der Ansichtsdatei. Zum Beispiel „fr“ in der Datei Index.fr.cshtml.

• AddDataAnnotationsLocalization fügt Unterstützung für lokalisierte DataAnnotations-Validierungsmeldungen durch Abstraktionen von IStringLocalizer hinzu.

Hinweis

Sie können unter Umständen keine Dezimaltrennzeichen in Dezimalfelder eingeben. Zur Unterstützung der jQuery-Validierung für nicht englische Gebietsschemas, in denen ein Komma („,“) als Dezimaltrennzeichen verwendet wird, und Nicht-US-englische Datums- und Uhrzeitformate müssen Sie Schritte zur Globalisierung Ihrer App ausführen. In diesem GitHub-Kommentar 4076 finden Sie Anweisungen zum Hinzufügen von Kommas als Dezimaltrennzeichen.

Nächste Schritte

Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:

• Bereitstellen der lokalisierten Ressourcen für die von der App unterstützten Sprachen und Kulturen
• 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
• Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App
• 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