Globalisierung und Lokalisierung in ASP.NET CoreGlobalization and localization in ASP.NET Core

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

Eine mehrsprachige Website ermöglicht es, eine größere Zielgruppe zu erreichen.A multilingual website allows the site to reach a wider audience. ASP.NET Core bietet Dienste und Middleware zur Lokalisierung in verschiedene Sprachen und Kulturen.ASP.NET Core provides services and middleware for localizing into different languages and cultures.

Die Internationalisierung umfasst dieGlobalisierung und die Lokalisierung.Internationalization involves Globalization and Localization. Globalisierung bezeichnet das Entwerfen von Anwendungen, die verschiedene Kulturen unterstützen.Globalization is the process of designing apps that support different cultures. Durch die Globalisierung wird die Unterstützung von Eingabe, Anzeige und Ausgabe mehrerer definierter Sprachskripts hinzugefügt, die zu bestimmten geografischen Bereichen gehören.Globalization adds support for input, display, and output of a defined set of language scripts that relate to specific geographic areas.

Durch die Lokalisierung wird eine globalisierte App, die bereits auf Lokalisierbarkeit vorbereitet wurde, auf eine bestimmte Kultur bzw. ein bestimmtes Gebietsschema angepasst.Localization is the process of adapting a globalized app, which you have already processed for localizability, to a particular culture/locale. Weitere Informationen finden Sie unter Begriffe für die Globalisierung und Lokalisierung am Ende dieses Dokuments.For more information see Globalization and localization terms near the end of this document.

Die Lokalisierung von Apps umfasst die folgenden Aufgaben:App localization involves the following:

  1. Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable
  2. Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support
  3. Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable

IStringLocalizer und IStringLocalizer<T> wurden zur Förderung der Produktivität bei der Entwicklung von lokalisierten Apps entwickelt.IStringLocalizer and IStringLocalizer<T> were architected to improve productivity when developing localized apps. IStringLocalizer verwendet ResourceManager und ResourceReader, um kulturspezifische Ressourcen zur Laufzeit bereitzustellen.IStringLocalizer uses the ResourceManager and ResourceReader to provide culture-specific resources at run time. Die Schnittstelle besitzt einen Indexer und IEnumerable für die Rückgabe von lokalisierten Zeichenfolgen.The interface has an indexer and an IEnumerable for returning localized strings. IStringLocalizer erfordert nicht, dass die Zeichenfolgen der Standardsprache in einer Ressourcendatei gespeichert werden.IStringLocalizer doesn't require storing the default language strings in a resource file. Sie können eine App entwickeln, die für die Lokalisierung ausgelegt ist, und müssen in den frühen Entwicklungsphasen keine Ressourcendateien erstellen.You can develop an app targeted for localization and not need to create resource files early in development. Im folgenden Codebeispiel wird dargestellt, wie die Zeichenfolge „About Title“ für die Lokalisierung umschlossen wird.The code below shows how to wrap the string "About Title" for localization.

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.In the preceding code, the IStringLocalizer<T> implementation comes from Dependency Injection. Wenn kein lokalisierter Wert von „About Title“ gefunden wird, wird der Indexerschlüssel zurückgegeben, d.h. die Zeichenfolge „About Title“.If the localized value of "About Title" isn't found, then the indexer key is returned, that is, the string "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.You can leave the default language literal strings in the app and wrap them in the localizer, so that you can focus on developing the app. Entwickeln Sie Ihre App mit Ihrer Standardsprache, und bereiten Sie sie auf die Lokalisierung vor, ohne zuerst eine Standardressourcendatei zu erstellen.You develop your app with your default language and prepare it for the localization step without first creating a default resource file. Alternativ können Sie das herkömmliche Verfahren verwenden und einen Schlüssel zum Abrufen der Zeichenfolge in der Standardsprache angeben.Alternatively, you can use the traditional approach and provide a key to retrieve the default language string. 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.For many developers the new workflow of not having a default language .resx file and simply wrapping the string literals can reduce the overhead of localizing an app. Andere Entwickler bevorzugen weiterhin den herkömmlichen Workflow, weil es dabei einfacher ist, mit längeren Literalzeichenfolgen zu arbeiten und lokalisierte Zeichenfolgen zu aktualisieren.Other developers will prefer the traditional work flow as it can make it easier to work with longer string literals and make it easier to update localized strings.

Verwenden Sie die Implementierung von IHtmlLocalizer<T> für Ressourcen, die HTML enthalten.Use the IHtmlLocalizer<T> implementation for resources that contain HTML. Mit IHtmlLocalizer werden Argumente HTML-codiert, die in der Ressourcenzeichenfolge formatiert sind. Die Ressourcenzeichenfolgen werden jedoch nicht HTML-codiert.IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself. Im folgenden Beispiel wird hervorgehoben, dass nur der Wert des Parameters name HTML-codiert ist.In the sample highlighted below, only the value of name parameter is HTML encoded.

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.Generally, only localize text, not HTML.

Auf der untersten Ebene können Sie IStringLocalizerFactory aus Dependency Injection abrufen:At the lowest level, you can get IStringLocalizerFactory out of Dependency Injection:

{
    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."];

Im obigen Codebeispiel werden beide factory.Create-Methoden veranschaulicht.The code above demonstrates each of the two factory create methods.

Sie können Ihre lokalisierten Zeichenfolgen in Steuerelemente und Bereiche aufteilen oder nur einen Container verwenden.You can partition your localized strings by controller, area, or have just one container. In der Beispiel-App wird eine Dummyklasse namens SharedResource für freigegebene Ressourcen verwendet.In the sample app, a dummy class named SharedResource is used for shared resources.

// Dummy class to group shared resources

namespace Localization
{
    public class SharedResource
    {
    }
}

Einige Entwickler verwenden die Klasse Startup, damit globale oder freigegebene Zeichenfolgen enthalten sind.Some developers use the Startup class to contain global or shared strings. Im folgenden Beispiel werden die Lokalisierer InfoController und SharedResource verwendet:In the sample below, the InfoController and the SharedResource localizers are used:

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 AnsichtView localization

Der Dienst IViewLocalizer gibt lokalisierte Zeichenfolgen für eine Ansicht an.The IViewLocalizer service provides localized strings for a view. Die Klasse ViewLocalizer implementiert diese Schnittstelle und sucht den Speicherort der Ressource über den Dateipfad der Ansicht.The ViewLocalizer class implements this interface and finds the resource location from the view file path. Im folgenden Codebeispiel wird die Verwendung der Standardimplementierung von IViewLocalizer veranschaulicht:The following code shows how to use the default implementation of IViewLocalizer:

@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.The default implementation of IViewLocalizer finds the resource file based on the view's file name. Es gibt keine Option zur Nutzung einer globalen freigegebenen Ressourcendatei.There's no option to use a global shared resource file. ViewLocalizer implementiert den Lokalisierer mithilfe von IHtmlLocalizer, damit Razor die lokalisierte Zeichenfolge nicht HTML-codiert.ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. Sie können Ressourcenzeichenfolgen parametrisieren, und IViewLocalizer codiert die Parameter mit HTML, aber nicht die Ressourcenzeichenfolgen.You can parameterize resource strings and IViewLocalizer will HTML encode the parameters, but not the resource string. Sehen Sie sich das folgende Razor-Markup an:Consider the following Razor markup:

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

Eine französische Ressourcendatei könnte Folgendes beinhalten:A French resource file could contain the following:

KeyKey WertValue
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

Die gerenderte Ansicht würde das HTML-Markup der Ressourcendatei enthalten.The rendered view would contain the HTML markup from the resource file.

Hinweis

Im Allgemeinen wird nur Text lokalisiert, nicht HTML.Generally, only localize text, not HTML.

Fügen Sie IHtmlLocalizer<T> ein, um eine freigegebene Ressourcendatei in einer Ansicht zu verwenden:To use a shared resource file in a view, inject IHtmlLocalizer<T>:

@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 DataAnnotationsDataAnnotations localization

Fehlermeldungen über DataAnnotations werden mit IStringLocalizer<T> lokalisiert.DataAnnotations error messages are localized with IStringLocalizer<T>. Durch Verwendung der Option ResourcesPath = "Resources" können die Fehlermeldungen in RegisterViewModel unter einem der folgenden Pfade gespeichert werden:Using the option ResourcesPath = "Resources", the error messages in RegisterViewModel can be stored in either of the following paths:

  • Resources/ViewModels.Account.RegisterViewModel.fr.resxResources/ViewModels.Account.RegisterViewModel.fr.resx
  • Resources/ViewModels/Account/RegisterViewModel.fr.resxResources/ViewModels/Account/RegisterViewModel.fr.resx
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; }
}

In ASP.NET Core MVC 1.1.0 und höher werden Attribute lokalisiert, die keine Validierungsattribute darstellen.In ASP.NET Core MVC 1.1.0 and higher, non-validation attributes are localized. ASP.NET Core MVC 1.0 sucht nicht nach lokalisierten Zeichenfolgen für Attribute, die keine Validierungsattribute darstellen.ASP.NET Core MVC 1.0 does not look up localized strings for non-validation attributes.

Verwenden einer Ressourcenzeichenfolge für mehrere KlassenUsing one resource string for multiple classes

Das folgende Codebeispiel zeigt, wie eine Ressourcenzeichenfolge für Validierungsattribute mit mehreren Klassen verwendet wird:The following code shows how to use one resource string for validation attributes with multiple classes:

public void ConfigureServices(IServiceCollection services)
{
    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 Ihre Validierungsmeldungen gespeichert sind.In the preceding code, SharedResource is the class corresponding to the resx where your validation messages are stored. DataAnnotations verwendet bei diesem Ansatz nur SharedResource anstelle der Ressource für jede Klasse.With this approach, DataAnnotations will only use SharedResource, rather than the resource for each class.

Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support

SupportedCultures und SupportedUICulturesSupportedCultures and SupportedUICultures

ASP.NET Core ermöglicht Ihnen, zwei Werte für die Kultur anzugeben: SupportedCultures und SupportedUICultures.ASP.NET Core allows you to specify two culture values, SupportedCultures and 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.The CultureInfo object for SupportedCultures determines the results of culture-dependent functions, such as date, time, number, and currency formatting. SupportedCultures bestimmt auch die Sortierreihenfolge von Texten, Groß-/Kleinschreibungskonventionen und Zeichenfolgenvergleichen.SupportedCultures also determines the sorting order of text, casing conventions, and string comparisons. Weitere Informationen darüber, wie der Server die Kultur abruft, finden Sie unter CultureInfo.CurrentCulture.See CultureInfo.CurrentCulture for more info on how the server gets the Culture. SupportedUICultures bestimmt, welche übersetzten Zeichenfolgen (aus den RESX-Dateien) von ResourceManager abgerufen werden.The SupportedUICultures determines which translated strings (from .resx files) are looked up by the ResourceManager. Die ResourceManager-Klasse sucht nach kulturspezifischen Zeichenfolgen, die durch CurrentUICulture bestimmt werden.The ResourceManager simply looks up culture-specific strings that's determined by CurrentUICulture. Jeder Thread in .NET enthält die Objekte CurrentCulture und CurrentUICulture.Every thread in .NET has CurrentCulture and CurrentUICulture objects. ASP.NET Core überprüft diese Werte beim Rendern von kulturspezifischen Funktionen.ASP.NET Core inspects these values when rendering culture-dependent functions. 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.For example, if the current thread's culture is set to "en-US" (English, United States), DateTime.Now.ToLongDateString() displays "Thursday, February 18, 2016", but if CurrentCulture is set to "es-ES" (Spanish, Spain) the output will be "jueves, 18 de febrero de 2016".

RessourcendateienResource files

Eine Ressourcendatei ist ein nützlicher Mechanismus für das Trennen von lokalisierbaren Zeichenfolgen von Code.A resource file is a useful mechanism for separating localizable strings from code. Übersetzte Zeichenfolgen für die Sprache, die nicht die Standardsprache darstellt, werden in RESX-Ressourcendateien isoliert.Translated strings for the non-default language are isolated in .resx resource files. Möglicherweise möchten Sie z.B. eine spanische Ressourcendatei namens Welcome.es.resx erstellen, die übersetzte Zeichenfolgen enthält.For example, you might want to create Spanish resource file named Welcome.es.resx containing translated strings. „es“ ist der Sprachcode für Spanisch."es" is the language code for Spanish. Erstellen dieser Ressourcendatei in Visual Studio:To create this resource file in Visual Studio:

  1. Führen Sie im Projektmappen-Explorer einen Rechtsklick auf den Ordner aus, der die Ressourcendatei enthalten soll, und klicken Sie dann auf Hinzufügen > Neues Element.In Solution Explorer, right click on the folder which will contain the resource file > Add > New Item.

    Geschachteltes Kontextmenü: Im Projektmappen-Explorer ist ein Kontextmenü für Ressourcen geöffnet.

  2. Geben Sie „resource“ (Ressource) im Feld Search installed templates (Installierte Vorlagen durchsuchen) ein, und benennen Sie die Datei.In the Search installed templates box, enter "resource" and name the file.

    Dialogfeld „Neues Element hinzufügen“

  3. Geben Sie den Schlüsselwert (native Zeichenfolge) in der Spalte Name und die übersetzte Zeichenfolge in der Spalte Wert ein.Enter the key value (native string) in the Name column and the translated string in the Value column.

    Welcome.es.resx-Datei (die Willkommensressourcendatei für Spanisch) mit dem Wort „Hello“ in der Spalte „Name“ und dem Wort „Hola“ (Hallo in Spanisch) in der Spalte „Wert“

    Die Datei Welcome.es.resx wird in Visual Studio angezeigt.Visual Studio shows the Welcome.es.resx file.

    Die Ressourcendatei „Welcome Spanish (es)“ im Projektmappen-Explorer

Benennung von RessourcendateienResource file naming

Ressourcen werden nach dem vollständigen Typnamen ihrer Klasse, abzüglich des Assemblynamens, benannt.Resources are named for the full type name of their class minus the assembly name. Eine französische Ressourcendatei, deren Hauptassembly für die Klasse LocalizationWebsite.Web.Startup``LocalizationWebsite.Web.dll ist, würde zum Beispiel den Namen Startup.fr.resx erhalten.For example, a French resource in a project whose main assembly is LocalizationWebsite.Web.dll for the class LocalizationWebsite.Web.Startup would be named Startup.fr.resx. Eine Ressource für die Klasse LocalizationWebsite.Web.Controllers.HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.A resource for the class LocalizationWebsite.Web.Controllers.HomeController would be named Controllers.HomeController.fr.resx. Wenn der Namespace Ihrer Zielklasse nicht dem Assemblynamen entspricht, benötigen Sie den vollständigen Typnamen.If your targeted class's namespace isn't the same as the assembly name you will need the full type name. Eine Ressource für den Typ ExtraNamespace.Tools im Beispielprojekt würde z.B. den Namen ExtraNamespace.Tools.fr.resx erhalten.For example, in the sample project a resource for the type ExtraNamespace.Tools would be named ExtraNamespace.Tools.fr.resx.

Im Beispielprojekt legt die Methode ConfigureServices die ResourcesPath-Eigenschaft auf „Resources“ fest. Der relative Projektpfad für den Controller „Home“ der französischen Ressourcendatei ist also Resources/Controllers.HomeController.fr.resx.In the sample project, the ConfigureServices method sets the ResourcesPath to "Resources", so the project relative path for the home controller's French resource file is Resources/Controllers.HomeController.fr.resx. Alternativ können Sie Ordner zum Organisieren von Ressourcendateien verwenden.Alternatively, you can use folders to organize resource files. Für den Controller „Home“ wäre der Pfad Resources/Controllers/HomeController.fr.resx.For the home controller, the path would be Resources/Controllers/HomeController.fr.resx. Wenn Sie die Option ResourcesPath nicht verwenden, würde sich die RESX-Datei im Basisprojektverzeichnis befinden.If you don't use the ResourcesPath option, the .resx file would go in the project base directory. Die Ressourcendatei für HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.The resource file for HomeController would be named Controllers.HomeController.fr.resx. Ob Sie die Benennungskonventionen mit Punkten oder wie Pfade verwenden, hängt davon ab, wie Sie Ihre Ressourcendateien organisieren möchten.The choice of using the dot or path naming convention depends on how you want to organize your resource files.

RessourcennameResource name Punkt- oder PfadbenennungDot or path naming
Resources/Controllers.HomeController.fr.resxResources/Controllers.HomeController.fr.resx PunktDot
Resources/Controllers/HomeController.fr.resxResources/Controllers/HomeController.fr.resx PfadPath

Ressourcendateien, die @inject IViewLocalizer in Razor-Ansichten verwenden, folgen einem ähnlichen Muster.Resource files using @inject IViewLocalizer in Razor views follow a similar pattern. Die Ressourcendatei für eine Ansicht kann mit der Punkt- oder Pfadbenennung benannt werden.The resource file for a view can be named using either dot naming or path naming. Ressourcendateien der Razor-Ansicht imitieren den Pfad ihrer zugehörigen Ansichtsdatei.Razor view resource files mimic the path of their associated view file. Wenn ResourcesPath zum Beispiel auf „Resources“ festgelegt wird, ist die französische Ressourcendatei, die der Ansicht Views/Home/About.cshtml zugeordnet ist, eine der folgenden zwei:Assuming we set the ResourcesPath to "Resources", the French resource file associated with the Views/Home/About.cshtml view could be either of the following:

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

  • Resources/Views.Home.About.fr.resxResources/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.If you don't use the ResourcesPath option, the .resx file for a view would be located in the same folder as the view.

RootNamespaceAttributeRootNamespaceAttribute

Das RootNamespace-Attribut stellt den Stammnamespace einer Assembly bereit, wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet.The RootNamespace attribute provides the root namespace of an assembly when the root namespace of an assembly is different than the assembly name.

Warnung

Dies kann vorkommen, wenn der Name eines Projekts kein gültiger .NET-Bezeichner ist.This can occur when a project's name is not a valid .NET identifier. Beispielsweise verwendet my-project-name.csproj den Stammnamespace my_project_name und den Assemblynamen my-project-name, der zu diesem Fehler führt.For instance my-project-name.csproj will use the root namespace my_project_name and the assembly name my-project-name leading to this error.

Wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet, dann geschieht Folgendes:If the root namespace of an assembly is different than the assembly name:

  • Die Lokalisierung funktioniert standardmäßig nicht.Localization does not work by default.
  • Die Lokalisierung schlägt aufgrund der Art und Weise, wie nach Ressourcen innerhalb der Assembly gesucht wird, fehl.Localization fails due to the way resources are searched for within the assembly. RootNamespace ist ein Buildzeitwert, der für den ausgeführten Prozess nicht verfügbar ist.RootNamespace is a build-time value which is not available to the executing process.

Wenn sich RootNamespace vom AssemblyName unterscheidet, schließen Sie Folgendes in AssemblyInfo.cs ein (mit den durch die aktuellen Werte ersetzten Parameterwerten):If the RootNamespace is different from the AssemblyName, include the following in AssemblyInfo.cs (with parameter values replaced with the actual values):

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.The preceding code enables the successful resolution of resx files.

KulturfallbackverhaltenCulture fallback behavior

Bei der Suche nach einer Ressource initiiert die Lokalisierung „Kulturfallbackverhalten“.When searching for a resource, localization engages in "culture fallback". Wenn die angeforderte Kultur nicht gefunden wird, setzt sie diese Kultur auf die übergeordnete Kultur zurück.Starting from the requested culture, if not found, it reverts to the parent culture of that culture. Die Eigenschaft CultureInfo.Parent stellt übrigens die übergeordnete Kultur dar.As an aside, the CultureInfo.Parent property represents the parent culture. Das bedeutet in der Regel (aber nicht immer), dass der nationale Bezeichner aus der ISO entfernt wird.This usually (but not always) means removing the national signifier from the ISO. Beispielsweise ist der in Mexiko gesprochene spanische Sprache „es-MX“.For example, the dialect of Spanish spoken in Mexico is "es-MX". „es“—Spanisch ist das übergeordnete Element und bezieht sich nicht auf ein einzelnes Land.It has the parent "es"—Spanish non-specific to any country.

Nehmen Sie an, dass Ihre Website eine Anforderung für eine Willkommensressource mit der Kultur „fr-CA“ erhält.Imagine your site receives a request for a "Welcome" resource using culture "fr-CA". Das Lokalisierungssystem sucht der Reihenfolge nach nach der folgenden Ressource und wählt die erste Übereinstimmung aus:The localization system looks for the following resources, in order, and selects the first match:

  • Welcome.fr-CA.resxWelcome.fr-CA.resx
  • Welcome.fr.resxWelcome.fr.resx
  • Welcome.resx (wenn NeutralResourcesLanguage „fr-CA“ ist)Welcome.resx (if the NeutralResourcesLanguage is "fr-CA")

Wenn Sie beispielsweise den Kulturkennzeichner „.fr“ entfernen und die Kultur auf „Französisch“ festgelegt ist, wird die Standardressourcendatei gelesen, und Zeichenfolgen werden lokalisiert.As an example, if you remove the ".fr" culture designator and you have the culture set to French, the default resource file is read and strings are localized. Der Ressourcen-Manager kennzeichnet eine Standard- oder Fallbackressource, wenn keine Entsprechung für die angeforderte Kultur gefunden wird.The Resource manager designates a default or fallback resource for when nothing meets your requested culture. 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.If you want to just return the key when missing a resource for the requested culture you must not have a default resource file.

Erstellen von Ressourcendateien mit Visual StudioGenerate resource files with 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.If you create a resource file in Visual Studio without a culture in the file name (for example, Welcome.resx), Visual Studio will create a C# class with a property for each string. Das ist in der Regel nicht das, was Sie mit ASP.NET Core erreichen wollen.That's usually not what you want with ASP.NET Core. In der Regel gibt es keine Standard-RESX-Ressourcendatei (eine RESX-Datei ohne den Kulturnamen).You typically don't have a default .resx resource file (a .resx file without the culture name). Es wird empfohlen, dass Sie eine RESX-Datei mit einem Kulturnamen erstellen (z.B. Welcome.fr.resx).We suggest you create the .resx file with a culture name (for example Welcome.fr.resx). Wenn Sie eine RESX-Datei mit einem Kulturnamen erstellen, erstellt Visual Studio keine Klassendatei.When you create a .resx file with a culture name, Visual Studio won't generate the class file.

Hinzufügen von anderen KulturenAdd other cultures

Jede Kombination von Sprache und Kultur (mit Ausnahme der Standardsprache) erfordert eine eindeutige Ressourcendatei.Each language and culture combination (other than the default language) requires a unique resource file. Sie erstellen Ressourcendateien für verschiedene Kulturen und Gebietsschemas, indem Sie neue Ressourcendateien erstellen, in denen ISO-Sprachcodes im Dateinamen enthalten sind (z.B. en-us fr-ca, und en-gb).You create resource files for different cultures and locales by creating new resource files in which the ISO language codes are part of the file name (for example, en-us, fr-ca, and en-gb). Diese ISO-Codes werden zwischen dem Dateinamen und der Erweiterung .resx platziert, z.B. Welcome.es-MX.resx (Spanisch/Mexiko).These ISO codes are placed between the file name and the .resx file extension, as in Welcome.es-MX.resx (Spanish/Mexico).

Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Konfigurieren der LokalisierungConfigure localization

Die Lokalisierung wird über die Methode Startup.ConfigureServices konfiguriert:Localization is configured in the Startup.ConfigureServices method:

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();
  • AddLocalization fügt die Lokalisierungsdienste dem Dienstcontainer hinzu.AddLocalization adds the localization services to the services container. Im obigen Codebeispiel wird der Ressourcenpfad auf „Resources“ festgelegt.The code above also sets the resources path to "Resources".

  • AddViewLocalization fügt Unterstützung für lokalisierte Ansichtsdateien hinzu.AddViewLocalization adds support for localized view files. In diesem Beispiel basiert die Lokalisierung der Ansicht auf dem Suffix der Ansichtsdatei.In this sample view localization is based on the view file suffix. Zum Beispiel „fr“ in der Datei Index.fr.cshtml.For example "fr" in the Index.fr.cshtml file.

  • AddDataAnnotationsLocalization fügt Unterstützung für lokalisierte DataAnnotations-Validierungsmeldungen durch Abstraktionen von IStringLocalizer hinzu.AddDataAnnotationsLocalization adds support for localized DataAnnotations validation messages through IStringLocalizer abstractions.

LokalisierungsmiddlewareLocalization middleware

Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt.The current culture on a request is set in the localization Middleware. Die Middleware für die Lokalisierung wird in der Startup.Configure-Methode aktiviert.The localization middleware is enabled in the Startup.Configure method. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z.B. app.UseMvcWithDefaultRoute()).The localization middleware must be configured before any middleware which might check the request culture (for example, app.UseMvcWithDefaultRoute()).

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

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

app.UseAuthentication();

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

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt.UseRequestLocalization initializes a RequestLocalizationOptions object. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet.On every request the list of RequestCultureProvider in the RequestLocalizationOptions is enumerated and the first provider that can successfully determine the request culture is used. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions:The default providers come from the RequestLocalizationOptions class:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten.The default list goes from most specific to least specific. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen.Later in the article we'll see how you can change the order and even add a custom culture provider. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.If none of the providers can determine the request culture, the DefaultRequestCulture is used.

QueryStringRequestCultureProviderQueryStringRequestCultureProvider

Einige Apps verwenden eine Abfragezeichenfolge, um die /dotnet/api/system.globalization.cultureinfo?view=netcore-3.1 festzulegen.Some apps will use a query string to set the /dotnet/api/system.globalization.cultureinfo?view=netcore-3.1. Bei Apps, die die Ansätze cookie oder Accept-Language-Header verwenden, ist das Hinzufügen einer Abfragezeichenfolge zur URL für das Debuggen und Testen von Code nützlich.For apps that use the cookie or Accept-Language header approach, adding a query string to the URL is useful for debugging and testing code. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider registriert.By default, the QueryStringRequestCultureProvider is registered as the first localization provider in the RequestCultureProvider list. Sie übergeben die Abfragezeichenfolge-Parameter culture und ui-culture.You pass the query string parameters culture and ui-culture. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:The following example sets the specific culture (language and region) to Spanish/Mexico:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Wenn Sie nur eine der beiden Abfragezeichenfolgen (culture oder ui-culture) übergeben, setzt der Anbieter für Abfragezeichenfolgen beide Werte entsprechend der übergebenen Abfrage fest.If you only pass in one of the two (culture or ui-culture), the query string provider will set both values using the one you passed in. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture als auch UICulture wie folgt festgelegt:For example, setting just the culture will set both the Culture and the UICulture:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProviderCookieRequestCultureProvider

Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies.Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.Use the MakeCookieValue method to create a cookie.

CookieRequestCultureProvider DefaultCookieName gibt den Standardcookienamen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt.The CookieRequestCultureProvider DefaultCookieName returns the default cookie name used to track the user's preferred culture information. Der Standardcookiename lautet .AspNetCore.Culture.The default cookie name is .AspNetCore.Culture.

Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%, wobei c für Culture steht und uic für UICulture, zum Beispiel:The cookie format is c=%LANGCODE%|uic=%LANGCODE%, where c is Culture and uic is UICulture, for example:

c=en-UK|uic=en-US

Wenn Sie nur eine Kulturinformation und eine Benutzeroberflächenkultur angeben, wird die angegebene Kultur sowohl für die Kulturinformation als auch die Benutzeroberflächenkultur verwendet.If you only specify one of culture info and UI culture, the specified culture will be used for both culture info and UI culture.

Der Accept-Language-HTTP-HeaderThe Accept-Language HTTP header

Der Accept-Language-Header ist in den meisten Browsern konfigurierbar und war ursprünglich dafür gedacht, die Sprache des Benutzers anzugeben.The Accept-Language header is settable in most browsers and was originally intended to specify the user's language. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde.This setting indicates what the browser has been set to send or has inherited from the underlying operating system. Der Accept-Language-HTTP-Header einer Browseranfrage ist keine unfehlbare Methode zum Erkennen der bevorzugten Sprache des Benutzers (siehe Setting language preferences in a browser (Festlegen der bevorzugten Sprache in einem Browser)).The Accept-Language HTTP header from a browser request isn't an infallible way to detect the user's preferred language (see Setting language preferences in a browser). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.A production app should include a way for a user to customize their choice of culture.

Festlegen des Accept-Language-HTTP-Headers in Internet ExplorerSet the Accept-Language HTTP header in IE

  1. Klicken Sie auf das Zahnradsymbol und dann auf Internetoptionen.From the gear icon, tap Internet Options.

  2. Klicken Sie auf Sprachen.Tap Languages.

    Internetoptionen

  3. Klicken Sie auf Spracheinstellungen festlegen.Tap Set Language Preferences.

  4. Klicken Sie auf Sprache hinzufügen.Tap Add a language.

  5. Fügen Sie die Sprache hinzu.Add the language.

  6. Klicken Sie auf die Sprache und dann auf Nach oben.Tap the language, then tap Move Up.

Verwenden eines benutzerdefinierten AnbietersUse a custom provider

Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen.Suppose you want to let your customers store their language and culture in your databases. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft.You could write a provider to look up these values for the user. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:The following code shows how to add a custom provider:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
});

Verwenden Sie RequestLocalizationOptions, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.Use RequestLocalizationOptions to add or remove localization providers.

Programmgesteuertes Festlegen der KulturSet the culture programmatically

Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture.This sample Localization.StarterWeb project on GitHub contains UI to set the Culture. Die Datei Views/Shared/_SelectLanguagePartial.cshtml ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:The Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported cultures:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Die Datei Views/Shared/_SelectLanguagePartial.cshtml wird dem Abschnitt footer der Layoutdatei hinzugefügt, damit sie für alle Ansichten verfügbar ist:The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will be available to all views:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

Die Methode SetLanguage legt das Kulturcookie fest.The SetLanguage method sets the culture cookie.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Sie können _SelectLanguagePartial.cshtml dem Beispielcode für dieses Projekt nicht hinzufügen.You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.The Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor partial through the Dependency Injection container.

Routendaten und Abfragezeichenfolgen für die ModellbindungModel binding route data and query strings

Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.See Globalization behavior of model binding route data and query strings.

Begriffe für die Globalisierung und LokalisierungGlobalization and localization terms

Der Lokalisierungsprozess für Ihre App erfordert ein grundlegendes Verständnis von relevanten Zeichensätzen, die häufig in der modernen Softwareentwicklung verwendet werden, und von den Problemen, die mit ihnen zusammenhängen.The process of localizing your app also requires a basic understanding of relevant character sets commonly used in modern software development and an understanding of the issues associated with them. Obwohl alle Computer Text als Zahlen (Codes) speichern, speichern verschiedene Systeme denselben Text mit anderen Zahlen.Although all computers store text as numbers (codes), different systems store the same text using different numbers. Der Lokalisierungsprozess bezieht sich auf das Übersetzen der Benutzeroberfläche (UI) der App für eine spezifische Kultur bzw. ein bestimmtes Gebietsschema.The localization process refers to translating the app user interface (UI) for a specific culture/locale.

Lokalisierbarkeit ist ein Zwischenschritt zum Überprüfen, ob eine globalisierte App bereit für die Lokalisierung ist.Localizability is an intermediate process for verifying that a globalized app is ready for localization.

Das Format RFC 4646 für den Kulturnamen ist <languagecode2>-<country/regioncode2>, wobei <languagecode2> der Sprachcode und <country/regioncode2> der Unterkulturcode.The RFC 4646 format for the culture name is <languagecode2>-<country/regioncode2>, where <languagecode2> is the language code and <country/regioncode2> is the subculture code. Zum Beispiel steht es-CL für Spanisch (Chile), en-US für Englisch (USA) und en-AU für Englisch (Australien).For example, es-CL for Spanish (Chile), en-US for English (United States), and en-AU for English (Australia). RFC 4646 ist eine Kombination der ISO 639, bei der zwei Kleinbuchstaben den Kulturcode beschreiben, der einer Sprache zugeordnet ist, und der ISO 3166, bei der zwei Großbuchstaben den Unterkulturcode beschreiben, der einem Land oder einer Region zugeordnet ist.RFC 4646 is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Siehe /previous-versions/commerce-server/ee825488(v=cs.20).See /previous-versions/commerce-server/ee825488(v=cs.20).

Die Internationalisierung (Internationalization) wird oft mit „I18N“ abgekürzt.Internationalization is often abbreviated to "I18N". Diese Abkürzung verwendet den ersten und den letzten Buchstaben und die Anzahl der dazwischen liegenden Buchstaben, 18 steht also für die Menge der Buchstaben zwischen dem ersten „I“ und dem letzten „N“.The abbreviation takes the first and last letters and the number of letters between them, so 18 stands for the number of letters between the first "I" and the last "N". Das gleiche gilt für Globalisierung (Globalization, G11N) und Lokalisierung (Localization, L10N).The same applies to Globalization (G11N), and Localization (L10N).

Begriffe:Terms:

  • Globalisierung (G11N): Der Prozess, durch den eine App mehrere Sprachen und Regionen unterstützen soll.Globalization (G11N): The process of making an app support different languages and regions.
  • Lokalisierung (L10N): Der Prozess, durch den eine App auf eine Sprache und Region angepasst wird.Localization (L10N): The process of customizing an app for a given language and region.
  • Internationalisierung (I18N): Beschreibt sowohl Globalisierung als auch Lokalisierung.Internationalization (I18N): Describes both globalization and localization.
  • Kultur: Beschreibt eine Sprache und optional auch eine Region.Culture: It's a language and, optionally, a region.
  • Neutrale Kultur: Eine Kultur, die eine bestimmte Sprache beschreibt, aber keine Region.Neutral culture: A culture that has a specified language, but not a region. (Zum Beispiel „en“, „es“)(for example "en", "es")
  • Spezifische Kultur: Eine Kultur, die eine bestimmte Sprache und Region beschreibt.Specific culture: A culture that has a specified language and region. (Zum Beispiel „en-US“, „en-GB“, „es-CL“)(for example "en-US", "en-GB", "es-CL")
  • Übergeordnete Kultur: Eine neutrale Kultur, die eine spezifische Kultur enthält.Parent culture: The neutral culture that contains a specific culture. („en“ ist z.B. die übergeordnete Kultur von „en-US“ und „en-GB“)(for example, "en" is the parent culture of "en-US" and "en-GB")
  • Gebietsschema: Ein Gebietsschema ist identisch mit einer Kultur.Locale: A locale is the same as a culture.

Hinweis

Sie können unter Umständen keine Dezimaltrennzeichen in Dezimalfelder eingeben.You may not be able to enter decimal commas in decimal fields. 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.To support jQuery validation for non-English locales that use a comma (",") for a decimal point, and non US-English date formats, you must take steps to globalize your app. In diesem GitHub-Problem 4076 finden Sie Anweisungen zum Hinzufügen von Kommas als Dezimaltrennzeichen.See this GitHub issue 4076 for instructions on adding decimal comma.

Hinweis

Web-Apps vor ASP.NET Core 3.0 schreiben ein Protokoll vom Typ LogLevel.Warning pro Anforderung, wenn die angeforderte Kultur nicht unterstützt wird.Prior to ASP.NET Core 3.0 web apps write one log of type LogLevel.Warning per request if the requested culture is unsupported. Durch die Protokollierung einer LogLevel.Warning pro Anforderung können große Protokolldateien mit redundanten Informationen entstehen.Logging one LogLevel.Warning per request is can make large log files with redundant information. Dieses Verhalten wurde in ASP.NET 3.0 geändert.This behavior has been changed in ASP.NET 3.0. Die RequestLocalizationMiddleware schreibt ein Protokoll vom Typ LogLevel.Debug, wodurch die Größe der Produktionsprotokolle reduziert wird.The RequestLocalizationMiddleware writes a log of type LogLevel.Debug, which reduces the size of production logs.

Zusätzliche RessourcenAdditional resources

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

Eine mehrsprachige Website ermöglicht es, eine größere Zielgruppe zu erreichen.A multilingual website allows the site to reach a wider audience. ASP.NET Core bietet Dienste und Middleware zur Lokalisierung in verschiedene Sprachen und Kulturen.ASP.NET Core provides services and middleware for localizing into different languages and cultures.

Die Internationalisierung umfasst dieGlobalisierung und die Lokalisierung.Internationalization involves Globalization and Localization. Globalisierung bezeichnet das Entwerfen von Anwendungen, die verschiedene Kulturen unterstützen.Globalization is the process of designing apps that support different cultures. Durch die Globalisierung wird die Unterstützung von Eingabe, Anzeige und Ausgabe mehrerer definierter Sprachskripts hinzugefügt, die zu bestimmten geografischen Bereichen gehören.Globalization adds support for input, display, and output of a defined set of language scripts that relate to specific geographic areas.

Durch die Lokalisierung wird eine globalisierte App, die bereits auf Lokalisierbarkeit vorbereitet wurde, auf eine bestimmte Kultur bzw. ein bestimmtes Gebietsschema angepasst.Localization is the process of adapting a globalized app, which you have already processed for localizability, to a particular culture/locale. Weitere Informationen finden Sie unter Begriffe für die Globalisierung und Lokalisierung am Ende dieses Dokuments.For more information see Globalization and localization terms near the end of this document.

Die Lokalisierung von Apps umfasst die folgenden Aufgaben:App localization involves the following:

  1. Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable
  2. Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support
  3. Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable

IStringLocalizer und IStringLocalizer<T> wurden zur Förderung der Produktivität bei der Entwicklung von lokalisierten Apps entwickelt.IStringLocalizer and IStringLocalizer<T> were architected to improve productivity when developing localized apps. IStringLocalizer verwendet ResourceManager und ResourceReader, um kulturspezifische Ressourcen zur Laufzeit bereitzustellen.IStringLocalizer uses the ResourceManager and ResourceReader to provide culture-specific resources at run time. Die Schnittstelle besitzt einen Indexer und IEnumerable für die Rückgabe von lokalisierten Zeichenfolgen.The interface has an indexer and an IEnumerable for returning localized strings. IStringLocalizer erfordert nicht, dass die Zeichenfolgen der Standardsprache in einer Ressourcendatei gespeichert werden.IStringLocalizer doesn't require storing the default language strings in a resource file. Sie können eine App entwickeln, die für die Lokalisierung ausgelegt ist, und müssen in den frühen Entwicklungsphasen keine Ressourcendateien erstellen.You can develop an app targeted for localization and not need to create resource files early in development. Im folgenden Codebeispiel wird dargestellt, wie die Zeichenfolge „About Title“ für die Lokalisierung umschlossen wird.The code below shows how to wrap the string "About Title" for localization.

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.In the preceding code, the IStringLocalizer<T> implementation comes from Dependency Injection. Wenn kein lokalisierter Wert von „About Title“ gefunden wird, wird der Indexerschlüssel zurückgegeben, d.h. die Zeichenfolge „About Title“.If the localized value of "About Title" isn't found, then the indexer key is returned, that is, the string "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.You can leave the default language literal strings in the app and wrap them in the localizer, so that you can focus on developing the app. Entwickeln Sie Ihre App mit Ihrer Standardsprache, und bereiten Sie sie auf die Lokalisierung vor, ohne zuerst eine Standardressourcendatei zu erstellen.You develop your app with your default language and prepare it for the localization step without first creating a default resource file. Alternativ können Sie das herkömmliche Verfahren verwenden und einen Schlüssel zum Abrufen der Zeichenfolge in der Standardsprache angeben.Alternatively, you can use the traditional approach and provide a key to retrieve the default language string. 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.For many developers the new workflow of not having a default language .resx file and simply wrapping the string literals can reduce the overhead of localizing an app. Andere Entwickler bevorzugen weiterhin den herkömmlichen Workflow, weil es dabei einfacher ist, mit längeren Literalzeichenfolgen zu arbeiten und lokalisierte Zeichenfolgen zu aktualisieren.Other developers will prefer the traditional work flow as it can make it easier to work with longer string literals and make it easier to update localized strings.

Verwenden Sie die Implementierung von IHtmlLocalizer<T> für Ressourcen, die HTML enthalten.Use the IHtmlLocalizer<T> implementation for resources that contain HTML. Mit IHtmlLocalizer werden Argumente HTML-codiert, die in der Ressourcenzeichenfolge formatiert sind. Die Ressourcenzeichenfolgen werden jedoch nicht HTML-codiert.IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself. Im folgenden Beispiel wird hervorgehoben, dass nur der Wert des Parameters name HTML-codiert ist.In the sample highlighted below, only the value of name parameter is HTML encoded.

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.Generally, only localize text, not HTML.

Auf der untersten Ebene können Sie IStringLocalizerFactory aus Dependency Injection abrufen:At the lowest level, you can get IStringLocalizerFactory out of Dependency Injection:

{
    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."];

Im obigen Codebeispiel werden beide factory.Create-Methoden veranschaulicht.The code above demonstrates each of the two factory create methods.

Sie können Ihre lokalisierten Zeichenfolgen in Steuerelemente und Bereiche aufteilen oder nur einen Container verwenden.You can partition your localized strings by controller, area, or have just one container. In der Beispiel-App wird eine Dummyklasse namens SharedResource für freigegebene Ressourcen verwendet.In the sample app, a dummy class named SharedResource is used for shared resources.

// Dummy class to group shared resources

namespace Localization
{
    public class SharedResource
    {
    }
}

Einige Entwickler verwenden die Klasse Startup, damit globale oder freigegebene Zeichenfolgen enthalten sind.Some developers use the Startup class to contain global or shared strings. Im folgenden Beispiel werden die Lokalisierer InfoController und SharedResource verwendet:In the sample below, the InfoController and the SharedResource localizers are used:

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 AnsichtView localization

Der Dienst IViewLocalizer gibt lokalisierte Zeichenfolgen für eine Ansicht an.The IViewLocalizer service provides localized strings for a view. Die Klasse ViewLocalizer implementiert diese Schnittstelle und sucht den Speicherort der Ressource über den Dateipfad der Ansicht.The ViewLocalizer class implements this interface and finds the resource location from the view file path. Im folgenden Codebeispiel wird die Verwendung der Standardimplementierung von IViewLocalizer veranschaulicht:The following code shows how to use the default implementation of IViewLocalizer:

@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.The default implementation of IViewLocalizer finds the resource file based on the view's file name. Es gibt keine Option zur Nutzung einer globalen freigegebenen Ressourcendatei.There's no option to use a global shared resource file. ViewLocalizer implementiert den Lokalisierer mithilfe von IHtmlLocalizer, damit Razor die lokalisierte Zeichenfolge nicht HTML-codiert.ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. Sie können Ressourcenzeichenfolgen parametrisieren, und IViewLocalizer codiert die Parameter mit HTML, aber nicht die Ressourcenzeichenfolgen.You can parameterize resource strings and IViewLocalizer will HTML encode the parameters, but not the resource string. Sehen Sie sich das folgende Razor-Markup an:Consider the following Razor markup:

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

Eine französische Ressourcendatei könnte Folgendes beinhalten:A French resource file could contain the following:

KeyKey WertValue
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

Die gerenderte Ansicht würde das HTML-Markup der Ressourcendatei enthalten.The rendered view would contain the HTML markup from the resource file.

Hinweis

Im Allgemeinen wird nur Text lokalisiert, nicht HTML.Generally, only localize text, not HTML.

Fügen Sie IHtmlLocalizer<T> ein, um eine freigegebene Ressourcendatei in einer Ansicht zu verwenden:To use a shared resource file in a view, inject IHtmlLocalizer<T>:

@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 DataAnnotationsDataAnnotations localization

Fehlermeldungen über DataAnnotations werden mit IStringLocalizer<T> lokalisiert.DataAnnotations error messages are localized with IStringLocalizer<T>. Durch Verwendung der Option ResourcesPath = "Resources" können die Fehlermeldungen in RegisterViewModel unter einem der folgenden Pfade gespeichert werden:Using the option ResourcesPath = "Resources", the error messages in RegisterViewModel can be stored in either of the following paths:

  • Resources/ViewModels.Account.RegisterViewModel.fr.resxResources/ViewModels.Account.RegisterViewModel.fr.resx
  • Resources/ViewModels/Account/RegisterViewModel.fr.resxResources/ViewModels/Account/RegisterViewModel.fr.resx
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; }
}

In ASP.NET Core MVC 1.1.0 und höher werden Attribute lokalisiert, die keine Validierungsattribute darstellen.In ASP.NET Core MVC 1.1.0 and higher, non-validation attributes are localized. ASP.NET Core MVC 1.0 sucht nicht nach lokalisierten Zeichenfolgen für Attribute, die keine Validierungsattribute darstellen.ASP.NET Core MVC 1.0 does not look up localized strings for non-validation attributes.

Verwenden einer Ressourcenzeichenfolge für mehrere KlassenUsing one resource string for multiple classes

Das folgende Codebeispiel zeigt, wie eine Ressourcenzeichenfolge für Validierungsattribute mit mehreren Klassen verwendet wird:The following code shows how to use one resource string for validation attributes with multiple classes:

public void ConfigureServices(IServiceCollection services)
{
    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 Ihre Validierungsmeldungen gespeichert sind.In the preceding code, SharedResource is the class corresponding to the resx where your validation messages are stored. DataAnnotations verwendet bei diesem Ansatz nur SharedResource anstelle der Ressource für jede Klasse.With this approach, DataAnnotations will only use SharedResource, rather than the resource for each class.

Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support

SupportedCultures und SupportedUICulturesSupportedCultures and SupportedUICultures

ASP.NET Core ermöglicht Ihnen, zwei Werte für die Kultur anzugeben: SupportedCultures und SupportedUICultures.ASP.NET Core allows you to specify two culture values, SupportedCultures and 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.The CultureInfo object for SupportedCultures determines the results of culture-dependent functions, such as date, time, number, and currency formatting. SupportedCultures bestimmt auch die Sortierreihenfolge von Texten, Groß-/Kleinschreibungskonventionen und Zeichenfolgenvergleichen.SupportedCultures also determines the sorting order of text, casing conventions, and string comparisons. Weitere Informationen darüber, wie der Server die Kultur abruft, finden Sie unter CultureInfo.CurrentCulture.See CultureInfo.CurrentCulture for more info on how the server gets the Culture. SupportedUICultures bestimmt, welche übersetzten Zeichenfolgen (aus den RESX-Dateien) von ResourceManager abgerufen werden.The SupportedUICultures determines which translated strings (from .resx files) are looked up by the ResourceManager. Die ResourceManager-Klasse sucht nach kulturspezifischen Zeichenfolgen, die durch CurrentUICulture bestimmt werden.The ResourceManager simply looks up culture-specific strings that's determined by CurrentUICulture. Jeder Thread in .NET enthält die Objekte CurrentCulture und CurrentUICulture.Every thread in .NET has CurrentCulture and CurrentUICulture objects. ASP.NET Core überprüft diese Werte beim Rendern von kulturspezifischen Funktionen.ASP.NET Core inspects these values when rendering culture-dependent functions. 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.For example, if the current thread's culture is set to "en-US" (English, United States), DateTime.Now.ToLongDateString() displays "Thursday, February 18, 2016", but if CurrentCulture is set to "es-ES" (Spanish, Spain) the output will be "jueves, 18 de febrero de 2016".

RessourcendateienResource files

Eine Ressourcendatei ist ein nützlicher Mechanismus für das Trennen von lokalisierbaren Zeichenfolgen von Code.A resource file is a useful mechanism for separating localizable strings from code. Übersetzte Zeichenfolgen für die Sprache, die nicht die Standardsprache darstellt, werden in RESX-Ressourcendateien isoliert.Translated strings for the non-default language are isolated in .resx resource files. Möglicherweise möchten Sie z.B. eine spanische Ressourcendatei namens Welcome.es.resx erstellen, die übersetzte Zeichenfolgen enthält.For example, you might want to create Spanish resource file named Welcome.es.resx containing translated strings. „es“ ist der Sprachcode für Spanisch."es" is the language code for Spanish. Erstellen dieser Ressourcendatei in Visual Studio:To create this resource file in Visual Studio:

  1. Führen Sie im Projektmappen-Explorer einen Rechtsklick auf den Ordner aus, der die Ressourcendatei enthalten soll, und klicken Sie dann auf Hinzufügen > Neues Element.In Solution Explorer, right click on the folder which will contain the resource file > Add > New Item.

    Geschachteltes Kontextmenü: Im Projektmappen-Explorer ist ein Kontextmenü für Ressourcen geöffnet.

  2. Geben Sie „resource“ (Ressource) im Feld Search installed templates (Installierte Vorlagen durchsuchen) ein, und benennen Sie die Datei.In the Search installed templates box, enter "resource" and name the file.

    Dialogfeld „Neues Element hinzufügen“

  3. Geben Sie den Schlüsselwert (native Zeichenfolge) in der Spalte Name und die übersetzte Zeichenfolge in der Spalte Wert ein.Enter the key value (native string) in the Name column and the translated string in the Value column.

    Welcome.es.resx-Datei (die Willkommensressourcendatei für Spanisch) mit dem Wort „Hello“ in der Spalte „Name“ und dem Wort „Hola“ (Hallo in Spanisch) in der Spalte „Wert“

    Die Datei Welcome.es.resx wird in Visual Studio angezeigt.Visual Studio shows the Welcome.es.resx file.

    Die Ressourcendatei „Welcome Spanish (es)“ im Projektmappen-Explorer

Benennung von RessourcendateienResource file naming

Ressourcen werden nach dem vollständigen Typnamen ihrer Klasse, abzüglich des Assemblynamens, benannt.Resources are named for the full type name of their class minus the assembly name. Eine französische Ressourcendatei, deren Hauptassembly für die Klasse LocalizationWebsite.Web.Startup``LocalizationWebsite.Web.dll ist, würde zum Beispiel den Namen Startup.fr.resx erhalten.For example, a French resource in a project whose main assembly is LocalizationWebsite.Web.dll for the class LocalizationWebsite.Web.Startup would be named Startup.fr.resx. Eine Ressource für die Klasse LocalizationWebsite.Web.Controllers.HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.A resource for the class LocalizationWebsite.Web.Controllers.HomeController would be named Controllers.HomeController.fr.resx. Wenn der Namespace Ihrer Zielklasse nicht dem Assemblynamen entspricht, benötigen Sie den vollständigen Typnamen.If your targeted class's namespace isn't the same as the assembly name you will need the full type name. Eine Ressource für den Typ ExtraNamespace.Tools im Beispielprojekt würde z.B. den Namen ExtraNamespace.Tools.fr.resx erhalten.For example, in the sample project a resource for the type ExtraNamespace.Tools would be named ExtraNamespace.Tools.fr.resx.

Im Beispielprojekt legt die Methode ConfigureServices die ResourcesPath-Eigenschaft auf „Resources“ fest. Der relative Projektpfad für den Controller „Home“ der französischen Ressourcendatei ist also Resources/Controllers.HomeController.fr.resx.In the sample project, the ConfigureServices method sets the ResourcesPath to "Resources", so the project relative path for the home controller's French resource file is Resources/Controllers.HomeController.fr.resx. Alternativ können Sie Ordner zum Organisieren von Ressourcendateien verwenden.Alternatively, you can use folders to organize resource files. Für den Controller „Home“ wäre der Pfad Resources/Controllers/HomeController.fr.resx.For the home controller, the path would be Resources/Controllers/HomeController.fr.resx. Wenn Sie die Option ResourcesPath nicht verwenden, würde sich die RESX-Datei im Basisprojektverzeichnis befinden.If you don't use the ResourcesPath option, the .resx file would go in the project base directory. Die Ressourcendatei für HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.The resource file for HomeController would be named Controllers.HomeController.fr.resx. Ob Sie die Benennungskonventionen mit Punkten oder wie Pfade verwenden, hängt davon ab, wie Sie Ihre Ressourcendateien organisieren möchten.The choice of using the dot or path naming convention depends on how you want to organize your resource files.

RessourcennameResource name Punkt- oder PfadbenennungDot or path naming
Resources/Controllers.HomeController.fr.resxResources/Controllers.HomeController.fr.resx PunktDot
Resources/Controllers/HomeController.fr.resxResources/Controllers/HomeController.fr.resx PfadPath

Ressourcendateien, die @inject IViewLocalizer in Razor-Ansichten verwenden, folgen einem ähnlichen Muster.Resource files using @inject IViewLocalizer in Razor views follow a similar pattern. Die Ressourcendatei für eine Ansicht kann mit der Punkt- oder Pfadbenennung benannt werden.The resource file for a view can be named using either dot naming or path naming. Ressourcendateien der Razor-Ansicht imitieren den Pfad ihrer zugehörigen Ansichtsdatei.Razor view resource files mimic the path of their associated view file. Wenn ResourcesPath zum Beispiel auf „Resources“ festgelegt wird, ist die französische Ressourcendatei, die der Ansicht Views/Home/About.cshtml zugeordnet ist, eine der folgenden zwei:Assuming we set the ResourcesPath to "Resources", the French resource file associated with the Views/Home/About.cshtml view could be either of the following:

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

  • Resources/Views.Home.About.fr.resxResources/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.If you don't use the ResourcesPath option, the .resx file for a view would be located in the same folder as the view.

RootNamespaceAttributeRootNamespaceAttribute

Das RootNamespace-Attribut stellt den Stammnamespace einer Assembly bereit, wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet.The RootNamespace attribute provides the root namespace of an assembly when the root namespace of an assembly is different than the assembly name.

Warnung

Dies kann vorkommen, wenn der Name eines Projekts kein gültiger .NET-Bezeichner ist.This can occur when a project's name is not a valid .NET identifier. Beispielsweise verwendet my-project-name.csproj den Stammnamespace my_project_name und den Assemblynamen my-project-name, der zu diesem Fehler führt.For instance my-project-name.csproj will use the root namespace my_project_name and the assembly name my-project-name leading to this error.

Wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet, dann geschieht Folgendes:If the root namespace of an assembly is different than the assembly name:

  • Die Lokalisierung funktioniert standardmäßig nicht.Localization does not work by default.
  • Die Lokalisierung schlägt aufgrund der Art und Weise, wie nach Ressourcen innerhalb der Assembly gesucht wird, fehl.Localization fails due to the way resources are searched for within the assembly. RootNamespace ist ein Buildzeitwert, der für den ausgeführten Prozess nicht verfügbar ist.RootNamespace is a build-time value which is not available to the executing process.

Wenn sich RootNamespace vom AssemblyName unterscheidet, schließen Sie Folgendes in AssemblyInfo.cs ein (mit den durch die aktuellen Werte ersetzten Parameterwerten):If the RootNamespace is different from the AssemblyName, include the following in AssemblyInfo.cs (with parameter values replaced with the actual values):

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.The preceding code enables the successful resolution of resx files.

KulturfallbackverhaltenCulture fallback behavior

Bei der Suche nach einer Ressource initiiert die Lokalisierung „Kulturfallbackverhalten“.When searching for a resource, localization engages in "culture fallback". Wenn die angeforderte Kultur nicht gefunden wird, setzt sie diese Kultur auf die übergeordnete Kultur zurück.Starting from the requested culture, if not found, it reverts to the parent culture of that culture. Die Eigenschaft CultureInfo.Parent stellt übrigens die übergeordnete Kultur dar.As an aside, the CultureInfo.Parent property represents the parent culture. Das bedeutet in der Regel (aber nicht immer), dass der nationale Bezeichner aus der ISO entfernt wird.This usually (but not always) means removing the national signifier from the ISO. Beispielsweise ist der in Mexiko gesprochene spanische Sprache „es-MX“.For example, the dialect of Spanish spoken in Mexico is "es-MX". „es“—Spanisch ist das übergeordnete Element und bezieht sich nicht auf ein einzelnes Land.It has the parent "es"—Spanish non-specific to any country.

Nehmen Sie an, dass Ihre Website eine Anforderung für eine Willkommensressource mit der Kultur „fr-CA“ erhält.Imagine your site receives a request for a "Welcome" resource using culture "fr-CA". Das Lokalisierungssystem sucht der Reihenfolge nach nach der folgenden Ressource und wählt die erste Übereinstimmung aus:The localization system looks for the following resources, in order, and selects the first match:

  • Welcome.fr-CA.resxWelcome.fr-CA.resx
  • Welcome.fr.resxWelcome.fr.resx
  • Welcome.resx (wenn NeutralResourcesLanguage „fr-CA“ ist)Welcome.resx (if the NeutralResourcesLanguage is "fr-CA")

Wenn Sie beispielsweise den Kulturkennzeichner „.fr“ entfernen und die Kultur auf „Französisch“ festgelegt ist, wird die Standardressourcendatei gelesen, und Zeichenfolgen werden lokalisiert.As an example, if you remove the ".fr" culture designator and you have the culture set to French, the default resource file is read and strings are localized. Der Ressourcen-Manager kennzeichnet eine Standard- oder Fallbackressource, wenn keine Entsprechung für die angeforderte Kultur gefunden wird.The Resource manager designates a default or fallback resource for when nothing meets your requested culture. 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.If you want to just return the key when missing a resource for the requested culture you must not have a default resource file.

Erstellen von Ressourcendateien mit Visual StudioGenerate resource files with 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.If you create a resource file in Visual Studio without a culture in the file name (for example, Welcome.resx), Visual Studio will create a C# class with a property for each string. Das ist in der Regel nicht das, was Sie mit ASP.NET Core erreichen wollen.That's usually not what you want with ASP.NET Core. In der Regel gibt es keine Standard-RESX-Ressourcendatei (eine RESX-Datei ohne den Kulturnamen).You typically don't have a default .resx resource file (a .resx file without the culture name). Es wird empfohlen, dass Sie eine RESX-Datei mit einem Kulturnamen erstellen (z.B. Welcome.fr.resx).We suggest you create the .resx file with a culture name (for example Welcome.fr.resx). Wenn Sie eine RESX-Datei mit einem Kulturnamen erstellen, erstellt Visual Studio keine Klassendatei.When you create a .resx file with a culture name, Visual Studio won't generate the class file.

Hinzufügen von anderen KulturenAdd other cultures

Jede Kombination von Sprache und Kultur (mit Ausnahme der Standardsprache) erfordert eine eindeutige Ressourcendatei.Each language and culture combination (other than the default language) requires a unique resource file. Sie erstellen Ressourcendateien für verschiedene Kulturen und Gebietsschemas, indem Sie neue Ressourcendateien erstellen, in denen ISO-Sprachcodes im Dateinamen enthalten sind (z.B. en-us fr-ca, und en-gb).You create resource files for different cultures and locales by creating new resource files in which the ISO language codes are part of the file name (for example, en-us, fr-ca, and en-gb). Diese ISO-Codes werden zwischen dem Dateinamen und der Erweiterung .resx platziert, z.B. Welcome.es-MX.resx (Spanisch/Mexiko).These ISO codes are placed between the file name and the .resx file extension, as in Welcome.es-MX.resx (Spanish/Mexico).

Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Konfigurieren der LokalisierungConfigure localization

Die Lokalisierung wird über die Methode Startup.ConfigureServices konfiguriert:Localization is configured in the Startup.ConfigureServices method:

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();
  • AddLocalization fügt die Lokalisierungsdienste dem Dienstcontainer hinzu.AddLocalization adds the localization services to the services container. Im obigen Codebeispiel wird der Ressourcenpfad auf „Resources“ festgelegt.The code above also sets the resources path to "Resources".

  • AddViewLocalization fügt Unterstützung für lokalisierte Ansichtsdateien hinzu.AddViewLocalization adds support for localized view files. In diesem Beispiel basiert die Lokalisierung der Ansicht auf dem Suffix der Ansichtsdatei.In this sample view localization is based on the view file suffix. Zum Beispiel „fr“ in der Datei Index.fr.cshtml.For example "fr" in the Index.fr.cshtml file.

  • AddDataAnnotationsLocalization fügt Unterstützung für lokalisierte DataAnnotations-Validierungsmeldungen durch Abstraktionen von IStringLocalizer hinzu.AddDataAnnotationsLocalization adds support for localized DataAnnotations validation messages through IStringLocalizer abstractions.

LokalisierungsmiddlewareLocalization middleware

Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt.The current culture on a request is set in the localization Middleware. Die Middleware für die Lokalisierung wird in der Startup.Configure-Methode aktiviert.The localization middleware is enabled in the Startup.Configure method. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z.B. app.UseMvcWithDefaultRoute()).The localization middleware must be configured before any middleware which might check the request culture (for example, app.UseMvcWithDefaultRoute()).

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

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

app.UseAuthentication();

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

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt.UseRequestLocalization initializes a RequestLocalizationOptions object. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet.On every request the list of RequestCultureProvider in the RequestLocalizationOptions is enumerated and the first provider that can successfully determine the request culture is used. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions:The default providers come from the RequestLocalizationOptions class:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten.The default list goes from most specific to least specific. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen.Later in the article we'll see how you can change the order and even add a custom culture provider. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.If none of the providers can determine the request culture, the DefaultRequestCulture is used.

QueryStringRequestCultureProviderQueryStringRequestCultureProvider

Einige Apps verwenden eine Abfragezeichenfolge, um die /dotnet/api/system.globalization.cultureinfo?view=netcore-3.1 festzulegen.Some apps will use a query string to set the /dotnet/api/system.globalization.cultureinfo?view=netcore-3.1. Bei Apps, die die Ansätze cookie oder Accept-Language-Header verwenden, ist das Hinzufügen einer Abfragezeichenfolge zur URL für das Debuggen und Testen von Code nützlich.For apps that use the cookie or Accept-Language header approach, adding a query string to the URL is useful for debugging and testing code. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider registriert.By default, the QueryStringRequestCultureProvider is registered as the first localization provider in the RequestCultureProvider list. Sie übergeben die Abfragezeichenfolge-Parameter culture und ui-culture.You pass the query string parameters culture and ui-culture. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:The following example sets the specific culture (language and region) to Spanish/Mexico:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Wenn Sie nur eine der beiden Abfragezeichenfolgen (culture oder ui-culture) übergeben, setzt der Anbieter für Abfragezeichenfolgen beide Werte entsprechend der übergebenen Abfrage fest.If you only pass in one of the two (culture or ui-culture), the query string provider will set both values using the one you passed in. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture als auch UICulture wie folgt festgelegt:For example, setting just the culture will set both the Culture and the UICulture:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProviderCookieRequestCultureProvider

Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies.Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.Use the MakeCookieValue method to create a cookie.

CookieRequestCultureProvider DefaultCookieName gibt den Standardcookienamen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt.The CookieRequestCultureProvider DefaultCookieName returns the default cookie name used to track the user's preferred culture information. Der Standardcookiename lautet .AspNetCore.Culture.The default cookie name is .AspNetCore.Culture.

Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%, wobei c für Culture steht und uic für UICulture, zum Beispiel:The cookie format is c=%LANGCODE%|uic=%LANGCODE%, where c is Culture and uic is UICulture, for example:

c=en-UK|uic=en-US

Wenn Sie nur eine Kulturinformation und eine Benutzeroberflächenkultur angeben, wird die angegebene Kultur sowohl für die Kulturinformation als auch die Benutzeroberflächenkultur verwendet.If you only specify one of culture info and UI culture, the specified culture will be used for both culture info and UI culture.

Der Accept-Language-HTTP-HeaderThe Accept-Language HTTP header

Der Accept-Language-Header ist in den meisten Browsern konfigurierbar und war ursprünglich dafür gedacht, die Sprache des Benutzers anzugeben.The Accept-Language header is settable in most browsers and was originally intended to specify the user's language. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde.This setting indicates what the browser has been set to send or has inherited from the underlying operating system. Der Accept-Language-HTTP-Header einer Browseranfrage ist keine unfehlbare Methode zum Erkennen der bevorzugten Sprache des Benutzers (siehe Setting language preferences in a browser (Festlegen der bevorzugten Sprache in einem Browser)).The Accept-Language HTTP header from a browser request isn't an infallible way to detect the user's preferred language (see Setting language preferences in a browser). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.A production app should include a way for a user to customize their choice of culture.

Festlegen des Accept-Language-HTTP-Headers in Internet ExplorerSet the Accept-Language HTTP header in IE

  1. Klicken Sie auf das Zahnradsymbol und dann auf Internetoptionen.From the gear icon, tap Internet Options.

  2. Klicken Sie auf Sprachen.Tap Languages.

    Internetoptionen

  3. Klicken Sie auf Spracheinstellungen festlegen.Tap Set Language Preferences.

  4. Klicken Sie auf Sprache hinzufügen.Tap Add a language.

  5. Fügen Sie die Sprache hinzu.Add the language.

  6. Klicken Sie auf die Sprache und dann auf Nach oben.Tap the language, then tap Move Up.

Verwenden eines benutzerdefinierten AnbietersUse a custom provider

Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen.Suppose you want to let your customers store their language and culture in your databases. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft.You could write a provider to look up these values for the user. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:The following code shows how to add a custom provider:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.RequestCultureProviders.Insert(0, new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
});

Verwenden Sie RequestLocalizationOptions, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.Use RequestLocalizationOptions to add or remove localization providers.

Programmgesteuertes Festlegen der KulturSet the culture programmatically

Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture.This sample Localization.StarterWeb project on GitHub contains UI to set the Culture. Die Datei Views/Shared/_SelectLanguagePartial.cshtml ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:The Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported cultures:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Die Datei Views/Shared/_SelectLanguagePartial.cshtml wird dem Abschnitt footer der Layoutdatei hinzugefügt, damit sie für alle Ansichten verfügbar ist:The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will be available to all views:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

Die Methode SetLanguage legt das Kulturcookie fest.The SetLanguage method sets the culture cookie.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Sie können _SelectLanguagePartial.cshtml dem Beispielcode für dieses Projekt nicht hinzufügen.You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.The Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor partial through the Dependency Injection container.

Routendaten und Abfragezeichenfolgen für die ModellbindungModel binding route data and query strings

Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.See Globalization behavior of model binding route data and query strings.

Begriffe für die Globalisierung und LokalisierungGlobalization and localization terms

Der Lokalisierungsprozess für Ihre App erfordert ein grundlegendes Verständnis von relevanten Zeichensätzen, die häufig in der modernen Softwareentwicklung verwendet werden, und von den Problemen, die mit ihnen zusammenhängen.The process of localizing your app also requires a basic understanding of relevant character sets commonly used in modern software development and an understanding of the issues associated with them. Obwohl alle Computer Text als Zahlen (Codes) speichern, speichern verschiedene Systeme denselben Text mit anderen Zahlen.Although all computers store text as numbers (codes), different systems store the same text using different numbers. Der Lokalisierungsprozess bezieht sich auf das Übersetzen der Benutzeroberfläche (UI) der App für eine spezifische Kultur bzw. ein bestimmtes Gebietsschema.The localization process refers to translating the app user interface (UI) for a specific culture/locale.

Lokalisierbarkeit ist ein Zwischenschritt zum Überprüfen, ob eine globalisierte App bereit für die Lokalisierung ist.Localizability is an intermediate process for verifying that a globalized app is ready for localization.

Das Format RFC 4646 für den Kulturnamen ist <languagecode2>-<country/regioncode2>, wobei <languagecode2> der Sprachcode und <country/regioncode2> der Unterkulturcode.The RFC 4646 format for the culture name is <languagecode2>-<country/regioncode2>, where <languagecode2> is the language code and <country/regioncode2> is the subculture code. Zum Beispiel steht es-CL für Spanisch (Chile), en-US für Englisch (USA) und en-AU für Englisch (Australien).For example, es-CL for Spanish (Chile), en-US for English (United States), and en-AU for English (Australia). RFC 4646 ist eine Kombination der ISO 639, bei der zwei Kleinbuchstaben den Kulturcode beschreiben, der einer Sprache zugeordnet ist, und der ISO 3166, bei der zwei Großbuchstaben den Unterkulturcode beschreiben, der einem Land oder einer Region zugeordnet ist.RFC 4646 is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Siehe /previous-versions/commerce-server/ee825488(v=cs.20).See /previous-versions/commerce-server/ee825488(v=cs.20).

Die Internationalisierung (Internationalization) wird oft mit „I18N“ abgekürzt.Internationalization is often abbreviated to "I18N". Diese Abkürzung verwendet den ersten und den letzten Buchstaben und die Anzahl der dazwischen liegenden Buchstaben, 18 steht also für die Menge der Buchstaben zwischen dem ersten „I“ und dem letzten „N“.The abbreviation takes the first and last letters and the number of letters between them, so 18 stands for the number of letters between the first "I" and the last "N". Das gleiche gilt für Globalisierung (Globalization, G11N) und Lokalisierung (Localization, L10N).The same applies to Globalization (G11N), and Localization (L10N).

Begriffe:Terms:

  • Globalisierung (G11N): Der Prozess, durch den eine App mehrere Sprachen und Regionen unterstützen soll.Globalization (G11N): The process of making an app support different languages and regions.
  • Lokalisierung (L10N): Der Prozess, durch den eine App auf eine Sprache und Region angepasst wird.Localization (L10N): The process of customizing an app for a given language and region.
  • Internationalisierung (I18N): Beschreibt sowohl Globalisierung als auch Lokalisierung.Internationalization (I18N): Describes both globalization and localization.
  • Kultur: Beschreibt eine Sprache und optional auch eine Region.Culture: It's a language and, optionally, a region.
  • Neutrale Kultur: Eine Kultur, die eine bestimmte Sprache beschreibt, aber keine Region.Neutral culture: A culture that has a specified language, but not a region. (Zum Beispiel „en“, „es“)(for example "en", "es")
  • Spezifische Kultur: Eine Kultur, die eine bestimmte Sprache und Region beschreibt.Specific culture: A culture that has a specified language and region. (Zum Beispiel „en-US“, „en-GB“, „es-CL“)(for example "en-US", "en-GB", "es-CL")
  • Übergeordnete Kultur: Eine neutrale Kultur, die eine spezifische Kultur enthält.Parent culture: The neutral culture that contains a specific culture. („en“ ist z.B. die übergeordnete Kultur von „en-US“ und „en-GB“)(for example, "en" is the parent culture of "en-US" and "en-GB")
  • Gebietsschema: Ein Gebietsschema ist identisch mit einer Kultur.Locale: A locale is the same as a culture.

Hinweis

Sie können unter Umständen keine Dezimaltrennzeichen in Dezimalfelder eingeben.You may not be able to enter decimal commas in decimal fields. 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.To support jQuery validation for non-English locales that use a comma (",") for a decimal point, and non US-English date formats, you must take steps to globalize your app. In diesem GitHub-Problem 4076 finden Sie Anweisungen zum Hinzufügen von Kommas als Dezimaltrennzeichen.See this GitHub issue 4076 for instructions on adding decimal comma.

Zusätzliche RessourcenAdditional resources

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

Eine mehrsprachige Website ermöglicht es, eine größere Zielgruppe zu erreichen.A multilingual website allows the site to reach a wider audience. ASP.NET Core bietet Dienste und Middleware zur Lokalisierung in verschiedene Sprachen und Kulturen.ASP.NET Core provides services and middleware for localizing into different languages and cultures.

Die Internationalisierung umfasst dieGlobalisierung und die Lokalisierung.Internationalization involves Globalization and Localization. Globalisierung bezeichnet das Entwerfen von Anwendungen, die verschiedene Kulturen unterstützen.Globalization is the process of designing apps that support different cultures. Durch die Globalisierung wird die Unterstützung von Eingabe, Anzeige und Ausgabe mehrerer definierter Sprachskripts hinzugefügt, die zu bestimmten geografischen Bereichen gehören.Globalization adds support for input, display, and output of a defined set of language scripts that relate to specific geographic areas.

Durch die Lokalisierung wird eine globalisierte App, die bereits auf Lokalisierbarkeit vorbereitet wurde, auf eine bestimmte Kultur bzw. ein bestimmtes Gebietsschema angepasst.Localization is the process of adapting a globalized app, which you have already processed for localizability, to a particular culture/locale. Weitere Informationen finden Sie unter Begriffe für die Globalisierung und Lokalisierung am Ende dieses Dokuments.For more information see Globalization and localization terms near the end of this document.

Die Lokalisierung von Apps umfasst die folgenden Aufgaben:App localization involves the following:

  1. Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable
  2. Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support
  3. Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Stellen Sie sicher, dass der Inhalt der App lokalisierbar ist.Make the app's content localizable

IStringLocalizer und IStringLocalizer<T> wurden zur Förderung der Produktivität bei der Entwicklung von lokalisierten Apps entwickelt.IStringLocalizer and IStringLocalizer<T> were architected to improve productivity when developing localized apps. IStringLocalizer verwendet ResourceManager und ResourceReader, um kulturspezifische Ressourcen zur Laufzeit bereitzustellen.IStringLocalizer uses the ResourceManager and ResourceReader to provide culture-specific resources at run time. Die Schnittstelle besitzt einen Indexer und IEnumerable für die Rückgabe von lokalisierten Zeichenfolgen.The interface has an indexer and an IEnumerable for returning localized strings. IStringLocalizer erfordert nicht, dass die Zeichenfolgen der Standardsprache in einer Ressourcendatei gespeichert werden.IStringLocalizer doesn't require storing the default language strings in a resource file. Sie können eine App entwickeln, die für die Lokalisierung ausgelegt ist, und müssen in den frühen Entwicklungsphasen keine Ressourcendateien erstellen.You can develop an app targeted for localization and not need to create resource files early in development. Im folgenden Codebeispiel wird dargestellt, wie die Zeichenfolge „About Title“ für die Lokalisierung umschlossen wird.The code below shows how to wrap the string "About Title" for localization.

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.In the preceding code, the IStringLocalizer<T> implementation comes from Dependency Injection. Wenn kein lokalisierter Wert von „About Title“ gefunden wird, wird der Indexerschlüssel zurückgegeben, d.h. die Zeichenfolge „About Title“.If the localized value of "About Title" isn't found, then the indexer key is returned, that is, the string "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.You can leave the default language literal strings in the app and wrap them in the localizer, so that you can focus on developing the app. Entwickeln Sie Ihre App mit Ihrer Standardsprache, und bereiten Sie sie auf die Lokalisierung vor, ohne zuerst eine Standardressourcendatei zu erstellen.You develop your app with your default language and prepare it for the localization step without first creating a default resource file. Alternativ können Sie das herkömmliche Verfahren verwenden und einen Schlüssel zum Abrufen der Zeichenfolge in der Standardsprache angeben.Alternatively, you can use the traditional approach and provide a key to retrieve the default language string. 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.For many developers the new workflow of not having a default language .resx file and simply wrapping the string literals can reduce the overhead of localizing an app. Andere Entwickler bevorzugen weiterhin den herkömmlichen Workflow, weil es dabei einfacher ist, mit längeren Literalzeichenfolgen zu arbeiten und lokalisierte Zeichenfolgen zu aktualisieren.Other developers will prefer the traditional work flow as it can make it easier to work with longer string literals and make it easier to update localized strings.

Verwenden Sie die Implementierung von IHtmlLocalizer<T> für Ressourcen, die HTML enthalten.Use the IHtmlLocalizer<T> implementation for resources that contain HTML. Mit IHtmlLocalizer werden Argumente HTML-codiert, die in der Ressourcenzeichenfolge formatiert sind. Die Ressourcenzeichenfolgen werden jedoch nicht HTML-codiert.IHtmlLocalizer HTML encodes arguments that are formatted in the resource string, but doesn't HTML encode the resource string itself. Im folgenden Beispiel wird hervorgehoben, dass nur der Wert des Parameters name HTML-codiert ist.In the sample highlighted below, only the value of name parameter is HTML encoded.

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.Generally, only localize text, not HTML.

Auf der untersten Ebene können Sie IStringLocalizerFactory aus Dependency Injection abrufen:At the lowest level, you can get IStringLocalizerFactory out of Dependency Injection:

{
    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."];

Im obigen Codebeispiel werden beide factory.Create-Methoden veranschaulicht.The code above demonstrates each of the two factory create methods.

Sie können Ihre lokalisierten Zeichenfolgen in Steuerelemente und Bereiche aufteilen oder nur einen Container verwenden.You can partition your localized strings by controller, area, or have just one container. In der Beispiel-App wird eine Dummyklasse namens SharedResource für freigegebene Ressourcen verwendet.In the sample app, a dummy class named SharedResource is used for shared resources.

// Dummy class to group shared resources

namespace Localization
{
    public class SharedResource
    {
    }
}

Einige Entwickler verwenden die Klasse Startup, damit globale oder freigegebene Zeichenfolgen enthalten sind.Some developers use the Startup class to contain global or shared strings. Im folgenden Beispiel werden die Lokalisierer InfoController und SharedResource verwendet:In the sample below, the InfoController and the SharedResource localizers are used:

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 AnsichtView localization

Der Dienst IViewLocalizer gibt lokalisierte Zeichenfolgen für eine Ansicht an.The IViewLocalizer service provides localized strings for a view. Die Klasse ViewLocalizer implementiert diese Schnittstelle und sucht den Speicherort der Ressource über den Dateipfad der Ansicht.The ViewLocalizer class implements this interface and finds the resource location from the view file path. Im folgenden Codebeispiel wird die Verwendung der Standardimplementierung von IViewLocalizer veranschaulicht:The following code shows how to use the default implementation of IViewLocalizer:

@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.The default implementation of IViewLocalizer finds the resource file based on the view's file name. Es gibt keine Option zur Nutzung einer globalen freigegebenen Ressourcendatei.There's no option to use a global shared resource file. ViewLocalizer implementiert den Lokalisierer mithilfe von IHtmlLocalizer, damit Razor die lokalisierte Zeichenfolge nicht HTML-codiert.ViewLocalizer implements the localizer using IHtmlLocalizer, so Razor doesn't HTML encode the localized string. Sie können Ressourcenzeichenfolgen parametrisieren, und IViewLocalizer codiert die Parameter mit HTML, aber nicht die Ressourcenzeichenfolgen.You can parameterize resource strings and IViewLocalizer will HTML encode the parameters, but not the resource string. Sehen Sie sich das folgende Razor-Markup an:Consider the following Razor markup:

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

Eine französische Ressourcendatei könnte Folgendes beinhalten:A French resource file could contain the following:

KeyKey WertValue
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

Die gerenderte Ansicht würde das HTML-Markup der Ressourcendatei enthalten.The rendered view would contain the HTML markup from the resource file.

Hinweis

Im Allgemeinen wird nur Text lokalisiert, nicht HTML.Generally, only localize text, not HTML.

Fügen Sie IHtmlLocalizer<T> ein, um eine freigegebene Ressourcendatei in einer Ansicht zu verwenden:To use a shared resource file in a view, inject IHtmlLocalizer<T>:

@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 DataAnnotationsDataAnnotations localization

Fehlermeldungen über DataAnnotations werden mit IStringLocalizer<T> lokalisiert.DataAnnotations error messages are localized with IStringLocalizer<T>. Durch Verwendung der Option ResourcesPath = "Resources" können die Fehlermeldungen in RegisterViewModel unter einem der folgenden Pfade gespeichert werden:Using the option ResourcesPath = "Resources", the error messages in RegisterViewModel can be stored in either of the following paths:

  • Resources/ViewModels.Account.RegisterViewModel.fr.resxResources/ViewModels.Account.RegisterViewModel.fr.resx
  • Resources/ViewModels/Account/RegisterViewModel.fr.resxResources/ViewModels/Account/RegisterViewModel.fr.resx
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; }
}

In ASP.NET Core MVC 1.1.0 und höher werden Attribute lokalisiert, die keine Validierungsattribute darstellen.In ASP.NET Core MVC 1.1.0 and higher, non-validation attributes are localized. ASP.NET Core MVC 1.0 sucht nicht nach lokalisierten Zeichenfolgen für Attribute, die keine Validierungsattribute darstellen.ASP.NET Core MVC 1.0 does not look up localized strings for non-validation attributes.

Verwenden einer Ressourcenzeichenfolge für mehrere KlassenUsing one resource string for multiple classes

Das folgende Codebeispiel zeigt, wie eine Ressourcenzeichenfolge für Validierungsattribute mit mehreren Klassen verwendet wird:The following code shows how to use one resource string for validation attributes with multiple classes:

public void ConfigureServices(IServiceCollection services)
{
    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 Ihre Validierungsmeldungen gespeichert sind.In the preceding code, SharedResource is the class corresponding to the resx where your validation messages are stored. DataAnnotations verwendet bei diesem Ansatz nur SharedResource anstelle der Ressource für jede Klasse.With this approach, DataAnnotations will only use SharedResource, rather than the resource for each class.

Stellen Sie die lokalisierten Ressourcen für die unterstützten Sprachen und Kulturen bereit.Provide localized resources for the languages and cultures you support

SupportedCultures und SupportedUICulturesSupportedCultures and SupportedUICultures

ASP.NET Core ermöglicht Ihnen, zwei Werte für die Kultur anzugeben: SupportedCultures und SupportedUICultures.ASP.NET Core allows you to specify two culture values, SupportedCultures and 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.The CultureInfo object for SupportedCultures determines the results of culture-dependent functions, such as date, time, number, and currency formatting. SupportedCultures bestimmt auch die Sortierreihenfolge von Texten, Groß-/Kleinschreibungskonventionen und Zeichenfolgenvergleichen.SupportedCultures also determines the sorting order of text, casing conventions, and string comparisons. Weitere Informationen darüber, wie der Server die Kultur abruft, finden Sie unter CultureInfo.CurrentCulture.See CultureInfo.CurrentCulture for more info on how the server gets the Culture. SupportedUICultures bestimmt, welche übersetzten Zeichenfolgen (aus den RESX-Dateien) von ResourceManager abgerufen werden.The SupportedUICultures determines which translated strings (from .resx files) are looked up by the ResourceManager. Die ResourceManager-Klasse sucht nach kulturspezifischen Zeichenfolgen, die durch CurrentUICulture bestimmt werden.The ResourceManager simply looks up culture-specific strings that's determined by CurrentUICulture. Jeder Thread in .NET enthält die Objekte CurrentCulture und CurrentUICulture.Every thread in .NET has CurrentCulture and CurrentUICulture objects. ASP.NET Core überprüft diese Werte beim Rendern von kulturspezifischen Funktionen.ASP.NET Core inspects these values when rendering culture-dependent functions. 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.For example, if the current thread's culture is set to "en-US" (English, United States), DateTime.Now.ToLongDateString() displays "Thursday, February 18, 2016", but if CurrentCulture is set to "es-ES" (Spanish, Spain) the output will be "jueves, 18 de febrero de 2016".

RessourcendateienResource files

Eine Ressourcendatei ist ein nützlicher Mechanismus für das Trennen von lokalisierbaren Zeichenfolgen von Code.A resource file is a useful mechanism for separating localizable strings from code. Übersetzte Zeichenfolgen für die Sprache, die nicht die Standardsprache darstellt, werden in RESX-Ressourcendateien isoliert.Translated strings for the non-default language are isolated in .resx resource files. Möglicherweise möchten Sie z.B. eine spanische Ressourcendatei namens Welcome.es.resx erstellen, die übersetzte Zeichenfolgen enthält.For example, you might want to create Spanish resource file named Welcome.es.resx containing translated strings. „es“ ist der Sprachcode für Spanisch."es" is the language code for Spanish. Erstellen dieser Ressourcendatei in Visual Studio:To create this resource file in Visual Studio:

  1. Führen Sie im Projektmappen-Explorer einen Rechtsklick auf den Ordner aus, der die Ressourcendatei enthalten soll, und klicken Sie dann auf Hinzufügen > Neues Element.In Solution Explorer, right click on the folder which will contain the resource file > Add > New Item.

    Geschachteltes Kontextmenü: Im Projektmappen-Explorer ist ein Kontextmenü für Ressourcen geöffnet.

  2. Geben Sie „resource“ (Ressource) im Feld Search installed templates (Installierte Vorlagen durchsuchen) ein, und benennen Sie die Datei.In the Search installed templates box, enter "resource" and name the file.

    Dialogfeld „Neues Element hinzufügen“

  3. Geben Sie den Schlüsselwert (native Zeichenfolge) in der Spalte Name und die übersetzte Zeichenfolge in der Spalte Wert ein.Enter the key value (native string) in the Name column and the translated string in the Value column.

    Welcome.es.resx-Datei (die Willkommensressourcendatei für Spanisch) mit dem Wort „Hello“ in der Spalte „Name“ und dem Wort „Hola“ (Hallo in Spanisch) in der Spalte „Wert“

    Die Datei Welcome.es.resx wird in Visual Studio angezeigt.Visual Studio shows the Welcome.es.resx file.

    Die Ressourcendatei „Welcome Spanish (es)“ im Projektmappen-Explorer

Benennung von RessourcendateienResource file naming

Ressourcen werden nach dem vollständigen Typnamen ihrer Klasse, abzüglich des Assemblynamens, benannt.Resources are named for the full type name of their class minus the assembly name. Eine französische Ressourcendatei, deren Hauptassembly für die Klasse LocalizationWebsite.Web.Startup``LocalizationWebsite.Web.dll ist, würde zum Beispiel den Namen Startup.fr.resx erhalten.For example, a French resource in a project whose main assembly is LocalizationWebsite.Web.dll for the class LocalizationWebsite.Web.Startup would be named Startup.fr.resx. Eine Ressource für die Klasse LocalizationWebsite.Web.Controllers.HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.A resource for the class LocalizationWebsite.Web.Controllers.HomeController would be named Controllers.HomeController.fr.resx. Wenn der Namespace Ihrer Zielklasse nicht dem Assemblynamen entspricht, benötigen Sie den vollständigen Typnamen.If your targeted class's namespace isn't the same as the assembly name you will need the full type name. Eine Ressource für den Typ ExtraNamespace.Tools im Beispielprojekt würde z.B. den Namen ExtraNamespace.Tools.fr.resx erhalten.For example, in the sample project a resource for the type ExtraNamespace.Tools would be named ExtraNamespace.Tools.fr.resx.

Im Beispielprojekt legt die Methode ConfigureServices die ResourcesPath-Eigenschaft auf „Resources“ fest. Der relative Projektpfad für den Controller „Home“ der französischen Ressourcendatei ist also Resources/Controllers.HomeController.fr.resx.In the sample project, the ConfigureServices method sets the ResourcesPath to "Resources", so the project relative path for the home controller's French resource file is Resources/Controllers.HomeController.fr.resx. Alternativ können Sie Ordner zum Organisieren von Ressourcendateien verwenden.Alternatively, you can use folders to organize resource files. Für den Controller „Home“ wäre der Pfad Resources/Controllers/HomeController.fr.resx.For the home controller, the path would be Resources/Controllers/HomeController.fr.resx. Wenn Sie die Option ResourcesPath nicht verwenden, würde sich die RESX-Datei im Basisprojektverzeichnis befinden.If you don't use the ResourcesPath option, the .resx file would go in the project base directory. Die Ressourcendatei für HomeController würde den Namen Controllers.HomeController.fr.resx erhalten.The resource file for HomeController would be named Controllers.HomeController.fr.resx. Ob Sie die Benennungskonventionen mit Punkten oder wie Pfade verwenden, hängt davon ab, wie Sie Ihre Ressourcendateien organisieren möchten.The choice of using the dot or path naming convention depends on how you want to organize your resource files.

RessourcennameResource name Punkt- oder PfadbenennungDot or path naming
Resources/Controllers.HomeController.fr.resxResources/Controllers.HomeController.fr.resx PunktDot
Resources/Controllers/HomeController.fr.resxResources/Controllers/HomeController.fr.resx PfadPath

Ressourcendateien, die @inject IViewLocalizer in Razor-Ansichten verwenden, folgen einem ähnlichen Muster.Resource files using @inject IViewLocalizer in Razor views follow a similar pattern. Die Ressourcendatei für eine Ansicht kann mit der Punkt- oder Pfadbenennung benannt werden.The resource file for a view can be named using either dot naming or path naming. Ressourcendateien der Razor-Ansicht imitieren den Pfad ihrer zugehörigen Ansichtsdatei.Razor view resource files mimic the path of their associated view file. Wenn ResourcesPath zum Beispiel auf „Resources“ festgelegt wird, ist die französische Ressourcendatei, die der Ansicht Views/Home/About.cshtml zugeordnet ist, eine der folgenden zwei:Assuming we set the ResourcesPath to "Resources", the French resource file associated with the Views/Home/About.cshtml view could be either of the following:

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

  • Resources/Views.Home.About.fr.resxResources/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.If you don't use the ResourcesPath option, the .resx file for a view would be located in the same folder as the view.

RootNamespaceAttributeRootNamespaceAttribute

Das RootNamespace-Attribut stellt den Stammnamespace einer Assembly bereit, wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet.The RootNamespace attribute provides the root namespace of an assembly when the root namespace of an assembly is different than the assembly name.

Warnung

Dies kann vorkommen, wenn der Name eines Projekts kein gültiger .NET-Bezeichner ist.This can occur when a project's name is not a valid .NET identifier. Beispielsweise verwendet my-project-name.csproj den Stammnamespace my_project_name und den Assemblynamen my-project-name, der zu diesem Fehler führt.For instance my-project-name.csproj will use the root namespace my_project_name and the assembly name my-project-name leading to this error.

Wenn der Stammnamespace einer Assembly sich vom Assemblynamen unterscheidet, dann geschieht Folgendes:If the root namespace of an assembly is different than the assembly name:

  • Die Lokalisierung funktioniert standardmäßig nicht.Localization does not work by default.
  • Die Lokalisierung schlägt aufgrund der Art und Weise, wie nach Ressourcen innerhalb der Assembly gesucht wird, fehl.Localization fails due to the way resources are searched for within the assembly. RootNamespace ist ein Buildzeitwert, der für den ausgeführten Prozess nicht verfügbar ist.RootNamespace is a build-time value which is not available to the executing process.

Wenn sich RootNamespace vom AssemblyName unterscheidet, schließen Sie Folgendes in AssemblyInfo.cs ein (mit den durch die aktuellen Werte ersetzten Parameterwerten):If the RootNamespace is different from the AssemblyName, include the following in AssemblyInfo.cs (with parameter values replaced with the actual values):

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.The preceding code enables the successful resolution of resx files.

KulturfallbackverhaltenCulture fallback behavior

Bei der Suche nach einer Ressource initiiert die Lokalisierung „Kulturfallbackverhalten“.When searching for a resource, localization engages in "culture fallback". Wenn die angeforderte Kultur nicht gefunden wird, setzt sie diese Kultur auf die übergeordnete Kultur zurück.Starting from the requested culture, if not found, it reverts to the parent culture of that culture. Die Eigenschaft CultureInfo.Parent stellt übrigens die übergeordnete Kultur dar.As an aside, the CultureInfo.Parent property represents the parent culture. Das bedeutet in der Regel (aber nicht immer), dass der nationale Bezeichner aus der ISO entfernt wird.This usually (but not always) means removing the national signifier from the ISO. Beispielsweise ist der in Mexiko gesprochene spanische Sprache „es-MX“.For example, the dialect of Spanish spoken in Mexico is "es-MX". „es“—Spanisch ist das übergeordnete Element und bezieht sich nicht auf ein einzelnes Land.It has the parent "es"—Spanish non-specific to any country.

Nehmen Sie an, dass Ihre Website eine Anforderung für eine Willkommensressource mit der Kultur „fr-CA“ erhält.Imagine your site receives a request for a "Welcome" resource using culture "fr-CA". Das Lokalisierungssystem sucht der Reihenfolge nach nach der folgenden Ressource und wählt die erste Übereinstimmung aus:The localization system looks for the following resources, in order, and selects the first match:

  • Welcome.fr-CA.resxWelcome.fr-CA.resx
  • Welcome.fr.resxWelcome.fr.resx
  • Welcome.resx (wenn NeutralResourcesLanguage „fr-CA“ ist)Welcome.resx (if the NeutralResourcesLanguage is "fr-CA")

Wenn Sie beispielsweise den Kulturkennzeichner „.fr“ entfernen und die Kultur auf „Französisch“ festgelegt ist, wird die Standardressourcendatei gelesen, und Zeichenfolgen werden lokalisiert.As an example, if you remove the ".fr" culture designator and you have the culture set to French, the default resource file is read and strings are localized. Der Ressourcen-Manager kennzeichnet eine Standard- oder Fallbackressource, wenn keine Entsprechung für die angeforderte Kultur gefunden wird.The Resource manager designates a default or fallback resource for when nothing meets your requested culture. 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.If you want to just return the key when missing a resource for the requested culture you must not have a default resource file.

Erstellen von Ressourcendateien mit Visual StudioGenerate resource files with 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.If you create a resource file in Visual Studio without a culture in the file name (for example, Welcome.resx), Visual Studio will create a C# class with a property for each string. Das ist in der Regel nicht das, was Sie mit ASP.NET Core erreichen wollen.That's usually not what you want with ASP.NET Core. In der Regel gibt es keine Standard-RESX-Ressourcendatei (eine RESX-Datei ohne den Kulturnamen).You typically don't have a default .resx resource file (a .resx file without the culture name). Es wird empfohlen, dass Sie eine RESX-Datei mit einem Kulturnamen erstellen (z.B. Welcome.fr.resx).We suggest you create the .resx file with a culture name (for example Welcome.fr.resx). Wenn Sie eine RESX-Datei mit einem Kulturnamen erstellen, erstellt Visual Studio keine Klassendatei.When you create a .resx file with a culture name, Visual Studio won't generate the class file.

Hinzufügen von anderen KulturenAdd other cultures

Jede Kombination von Sprache und Kultur (mit Ausnahme der Standardsprache) erfordert eine eindeutige Ressourcendatei.Each language and culture combination (other than the default language) requires a unique resource file. Sie erstellen Ressourcendateien für verschiedene Kulturen und Gebietsschemas, indem Sie neue Ressourcendateien erstellen, in denen ISO-Sprachcodes im Dateinamen enthalten sind (z.B. en-us fr-ca, und en-gb).You create resource files for different cultures and locales by creating new resource files in which the ISO language codes are part of the file name (for example, en-us, fr-ca, and en-gb). Diese ISO-Codes werden zwischen dem Dateinamen und der Erweiterung .resx platziert, z.B. Welcome.es-MX.resx (Spanisch/Mexiko).These ISO codes are placed between the file name and the .resx file extension, as in Welcome.es-MX.resx (Spanish/Mexico).

Implementieren Sie eine Strategie zum Auswählen der Sprache bzw. Kultur für jede Anforderung.Implement a strategy to select the language/culture for each request

Konfigurieren der LokalisierungConfigure localization

Die Lokalisierung wird über die Methode Startup.ConfigureServices konfiguriert:Localization is configured in the Startup.ConfigureServices method:

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();
  • AddLocalization fügt die Lokalisierungsdienste dem Dienstcontainer hinzu.AddLocalization adds the localization services to the services container. Im obigen Codebeispiel wird der Ressourcenpfad auf „Resources“ festgelegt.The code above also sets the resources path to "Resources".

  • AddViewLocalization fügt Unterstützung für lokalisierte Ansichtsdateien hinzu.AddViewLocalization adds support for localized view files. In diesem Beispiel basiert die Lokalisierung der Ansicht auf dem Suffix der Ansichtsdatei.In this sample view localization is based on the view file suffix. Zum Beispiel „fr“ in der Datei Index.fr.cshtml.For example "fr" in the Index.fr.cshtml file.

  • AddDataAnnotationsLocalization fügt Unterstützung für lokalisierte DataAnnotations-Validierungsmeldungen durch Abstraktionen von IStringLocalizer hinzu.AddDataAnnotationsLocalization adds support for localized DataAnnotations validation messages through IStringLocalizer abstractions.

LokalisierungsmiddlewareLocalization middleware

Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt.The current culture on a request is set in the localization Middleware. Die Middleware für die Lokalisierung wird in der Startup.Configure-Methode aktiviert.The localization middleware is enabled in the Startup.Configure method. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z.B. app.UseMvcWithDefaultRoute()).The localization middleware must be configured before any middleware which might check the request culture (for example, app.UseMvcWithDefaultRoute()).

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

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

app.UseAuthentication();

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

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt.UseRequestLocalization initializes a RequestLocalizationOptions object. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet.On every request the list of RequestCultureProvider in the RequestLocalizationOptions is enumerated and the first provider that can successfully determine the request culture is used. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions:The default providers come from the RequestLocalizationOptions class:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten.The default list goes from most specific to least specific. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen.Later in the article we'll see how you can change the order and even add a custom culture provider. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.If none of the providers can determine the request culture, the DefaultRequestCulture is used.

QueryStringRequestCultureProviderQueryStringRequestCultureProvider

Einige Apps verwenden eine Abfragezeichenfolge, um die CultureInfo festzulegen.Some apps will use a query string to set the CultureInfo. Bei Apps, die die Ansätze cookie oder Accept-Language-Header verwenden, ist das Hinzufügen einer Abfragezeichenfolge zur URL für das Debuggen und Testen von Code nützlich.For apps that use the cookie or Accept-Language header approach, adding a query string to the URL is useful for debugging and testing code. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider registriert.By default, the QueryStringRequestCultureProvider is registered as the first localization provider in the RequestCultureProvider list. Sie übergeben die Abfragezeichenfolge-Parameter culture und ui-culture.You pass the query string parameters culture and ui-culture. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:The following example sets the specific culture (language and region) to Spanish/Mexico:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Wenn Sie nur eine der beiden Abfragezeichenfolgen (culture oder ui-culture) übergeben, setzt der Anbieter für Abfragezeichenfolgen beide Werte entsprechend der übergebenen Abfrage fest.If you only pass in one of the two (culture or ui-culture), the query string provider will set both values using the one you passed in. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture als auch UICulture wie folgt festgelegt:For example, setting just the culture will set both the Culture and the UICulture:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProviderCookieRequestCultureProvider

Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies.Production apps will often provide a mechanism to set the culture with the ASP.NET Core culture cookie. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.Use the MakeCookieValue method to create a cookie.

CookieRequestCultureProvider DefaultCookieName gibt den Standardcookienamen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt.The CookieRequestCultureProvider DefaultCookieName returns the default cookie name used to track the user's preferred culture information. Der Standardcookiename lautet .AspNetCore.Culture.The default cookie name is .AspNetCore.Culture.

Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%, wobei c für Culture steht und uic für UICulture, zum Beispiel:The cookie format is c=%LANGCODE%|uic=%LANGCODE%, where c is Culture and uic is UICulture, for example:

c=en-UK|uic=en-US

Wenn Sie nur eine Kulturinformation und eine Benutzeroberflächenkultur angeben, wird die angegebene Kultur sowohl für die Kulturinformation als auch die Benutzeroberflächenkultur verwendet.If you only specify one of culture info and UI culture, the specified culture will be used for both culture info and UI culture.

Der Accept-Language-HTTP-HeaderThe Accept-Language HTTP header

Der Accept-Language-Header ist in den meisten Browsern konfigurierbar und war ursprünglich dafür gedacht, die Sprache des Benutzers anzugeben.The Accept-Language header is settable in most browsers and was originally intended to specify the user's language. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde.This setting indicates what the browser has been set to send or has inherited from the underlying operating system. Der Accept-Language-HTTP-Header einer Browseranfrage ist keine unfehlbare Methode zum Erkennen der bevorzugten Sprache des Benutzers (siehe Setting language preferences in a browser (Festlegen der bevorzugten Sprache in einem Browser)).The Accept-Language HTTP header from a browser request isn't an infallible way to detect the user's preferred language (see Setting language preferences in a browser). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.A production app should include a way for a user to customize their choice of culture.

Festlegen des Accept-Language-HTTP-Headers in Internet ExplorerSet the Accept-Language HTTP header in IE

  1. Klicken Sie auf das Zahnradsymbol und dann auf Internetoptionen.From the gear icon, tap Internet Options.

  2. Klicken Sie auf Sprachen.Tap Languages.

    Internetoptionen

  3. Klicken Sie auf Spracheinstellungen festlegen.Tap Set Language Preferences.

  4. Klicken Sie auf Sprache hinzufügen.Tap Add a language.

  5. Fügen Sie die Sprache hinzu.Add the language.

  6. Klicken Sie auf die Sprache und dann auf Nach oben.Tap the language, then tap Move Up.

Der Content-Language-HTTP-HeaderThe Content-Language HTTP header

Der Content-Language-Entitätsheader:The Content-Language entity header:

  • Wird verwendet, um die für die Zielgruppe vorgesehenen Sprachen zu beschreiben.Is used to describe the language(s) intended for the audience.
  • Ermöglicht einem Benutzer, gemäß seiner bevorzugten Sprache zu differenzieren.Allows a user to differentiate according to the users' own preferred language.

Entitätsheader werden in HTTP-Anforderungen und -Antworten verwendet.Entity headers are used in both HTTP requests and responses.

Der Content-Language-Header kann durch Festlegen der Eigenschaft ApplyCurrentCultureToResponseHeaders hinzugefügt werden.The Content-Language header can be added by setting the property ApplyCurrentCultureToResponseHeaders.

Hinzufügen des Content-Language-Headers:Adding the Content-Language header:

  • Ermöglicht RequestLocalizationMiddleware, den Content-Language-Header mit der CurrentUICulture festzulegen.Allows the RequestLocalizationMiddleware to set the Content-Language header with the CurrentUICulture.
  • Macht das explizite Festlegen des Content-Language-Antwortheaders überflüssig.Eliminates the need to set the response header Content-Language explicitly.
app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

Verwenden eines benutzerdefinierten AnbietersUse a custom provider

Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen.Suppose you want to let your customers store their language and culture in your databases. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft.You could write a provider to look up these values for the user. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:The following code shows how to add a custom provider:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return new ProviderCultureResult("en");
    }));
});

Verwenden Sie RequestLocalizationOptions, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.Use RequestLocalizationOptions to add or remove localization providers.

Programmgesteuertes Festlegen der KulturSet the culture programmatically

Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture.This sample Localization.StarterWeb project on GitHub contains UI to set the Culture. Die Datei Views/Shared/_SelectLanguagePartial.cshtml ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:The Views/Shared/_SelectLanguagePartial.cshtml file allows you to select the culture from the list of supported cultures:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Die Datei Views/Shared/_SelectLanguagePartial.cshtml wird dem Abschnitt footer der Layoutdatei hinzugefügt, damit sie für alle Ansichten verfügbar ist:The Views/Shared/_SelectLanguagePartial.cshtml file is added to the footer section of the layout file so it will be available to all views:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

Die Methode SetLanguage legt das Kulturcookie fest.The SetLanguage method sets the culture cookie.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Sie können _SelectLanguagePartial.cshtml dem Beispielcode für dieses Projekt nicht hinzufügen.You can't plug in the _SelectLanguagePartial.cshtml to sample code for this project. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.The Localization.StarterWeb project on GitHub has code to flow the RequestLocalizationOptions to a Razor partial through the Dependency Injection container.

Routendaten und Abfragezeichenfolgen für die ModellbindungModel binding route data and query strings

Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.See Globalization behavior of model binding route data and query strings.

Begriffe für die Globalisierung und LokalisierungGlobalization and localization terms

Der Lokalisierungsprozess für Ihre App erfordert ein grundlegendes Verständnis von relevanten Zeichensätzen, die häufig in der modernen Softwareentwicklung verwendet werden, und von den Problemen, die mit ihnen zusammenhängen.The process of localizing your app also requires a basic understanding of relevant character sets commonly used in modern software development and an understanding of the issues associated with them. Obwohl alle Computer Text als Zahlen (Codes) speichern, speichern verschiedene Systeme denselben Text mit anderen Zahlen.Although all computers store text as numbers (codes), different systems store the same text using different numbers. Der Lokalisierungsprozess bezieht sich auf das Übersetzen der Benutzeroberfläche (UI) der App für eine spezifische Kultur bzw. ein bestimmtes Gebietsschema.The localization process refers to translating the app user interface (UI) for a specific culture/locale.

Lokalisierbarkeit ist ein Zwischenschritt zum Überprüfen, ob eine globalisierte App bereit für die Lokalisierung ist.Localizability is an intermediate process for verifying that a globalized app is ready for localization.

Das Format RFC 4646 für den Kulturnamen ist <languagecode2>-<country/regioncode2>, wobei <languagecode2> der Sprachcode und <country/regioncode2> der Unterkulturcode.The RFC 4646 format for the culture name is <languagecode2>-<country/regioncode2>, where <languagecode2> is the language code and <country/regioncode2> is the subculture code. Zum Beispiel steht es-CL für Spanisch (Chile), en-US für Englisch (USA) und en-AU für Englisch (Australien).For example, es-CL for Spanish (Chile), en-US for English (United States), and en-AU for English (Australia). RFC 4646 ist eine Kombination der ISO 639, bei der zwei Kleinbuchstaben den Kulturcode beschreiben, der einer Sprache zugeordnet ist, und der ISO 3166, bei der zwei Großbuchstaben den Unterkulturcode beschreiben, der einem Land oder einer Region zugeordnet ist.RFC 4646 is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Siehe /previous-versions/commerce-server/ee825488(v=cs.20).See /previous-versions/commerce-server/ee825488(v=cs.20).

Die Internationalisierung (Internationalization) wird oft mit „I18N“ abgekürzt.Internationalization is often abbreviated to "I18N". Diese Abkürzung verwendet den ersten und den letzten Buchstaben und die Anzahl der dazwischen liegenden Buchstaben, 18 steht also für die Menge der Buchstaben zwischen dem ersten „I“ und dem letzten „N“.The abbreviation takes the first and last letters and the number of letters between them, so 18 stands for the number of letters between the first "I" and the last "N". Das gleiche gilt für Globalisierung (Globalization, G11N) und Lokalisierung (Localization, L10N).The same applies to Globalization (G11N), and Localization (L10N).

Begriffe:Terms:

  • Globalisierung (G11N): Der Prozess, durch den eine App mehrere Sprachen und Regionen unterstützen soll.Globalization (G11N): The process of making an app support different languages and regions.
  • Lokalisierung (L10N): Der Prozess, durch den eine App auf eine Sprache und Region angepasst wird.Localization (L10N): The process of customizing an app for a given language and region.
  • Internationalisierung (I18N): Beschreibt sowohl Globalisierung als auch Lokalisierung.Internationalization (I18N): Describes both globalization and localization.
  • Kultur: Beschreibt eine Sprache und optional auch eine Region.Culture: It's a language and, optionally, a region.
  • Neutrale Kultur: Eine Kultur, die eine bestimmte Sprache beschreibt, aber keine Region.Neutral culture: A culture that has a specified language, but not a region. (Zum Beispiel „en“, „es“)(for example "en", "es")
  • Spezifische Kultur: Eine Kultur, die eine bestimmte Sprache und Region beschreibt.Specific culture: A culture that has a specified language and region. (Zum Beispiel „en-US“, „en-GB“, „es-CL“)(for example "en-US", "en-GB", "es-CL")
  • Übergeordnete Kultur: Eine neutrale Kultur, die eine spezifische Kultur enthält.Parent culture: The neutral culture that contains a specific culture. („en“ ist z.B. die übergeordnete Kultur von „en-US“ und „en-GB“)(for example, "en" is the parent culture of "en-US" and "en-GB")
  • Gebietsschema: Ein Gebietsschema ist identisch mit einer Kultur.Locale: A locale is the same as a culture.

Hinweis

Sie können unter Umständen keine Dezimaltrennzeichen in Dezimalfelder eingeben.You may not be able to enter decimal commas in decimal fields. 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.To support jQuery validation for non-English locales that use a comma (",") for a decimal point, and non US-English date formats, you must take steps to globalize your app. In diesem GitHub-Problem 4076 finden Sie Anweisungen zum Hinzufügen von Kommas als Dezimaltrennzeichen.See this GitHub issue 4076 for instructions on adding decimal comma.

Hinweis

Web-Apps vor ASP.NET Core 3.0 schreiben ein Protokoll vom Typ LogLevel.Warning pro Anforderung, wenn die angeforderte Kultur nicht unterstützt wird.Prior to ASP.NET Core 3.0 web apps write one log of type LogLevel.Warning per request if the requested culture is unsupported. Durch die Protokollierung einer LogLevel.Warning pro Anforderung können große Protokolldateien mit redundanten Informationen entstehen.Logging one LogLevel.Warning per request is can make large log files with redundant information. Dieses Verhalten wurde in ASP.NET 3.0 geändert.This behavior has been changed in ASP.NET 3.0. Die RequestLocalizationMiddleware schreibt ein Protokoll vom Typ LogLevel.Debug, wodurch die Größe der Produktionsprotokolle reduziert wird.The RequestLocalizationMiddleware writes a log of type LogLevel.Debug, which reduces the size of production logs.

Zusätzliche RessourcenAdditional resources