Implementieren einer Strategie zum Auswählen der Sprache/Kultur für jede Anforderung in einer lokalisierten ASP.NET Core-App
Hinweis
Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
Warnung
Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
Wichtig
Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.
Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana und Rick Anderson
Eine Aufgabe zum Lokalisieren einer App besteht darin, eine Strategie zum Auswählen der geeigneten Kultur für jede Antwort zu implementieren, die die App zurückgibt.
Konfigurieren der Lokalisierungsmiddleware
Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt. Die Middleware für die Lokalisierung wird in Program.cs
aktiviert. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z. B. app.UseMvcWithDefaultRoute()
).
builder.Services.Configure<RequestLocalizationOptions>(options =>
{
var supportedCultures = new[] { "en-US", "fr" };
options.SetDefaultCulture(supportedCultures[0])
.AddSupportedCultures(supportedCultures)
.AddSupportedUICultures(supportedCultures);
});
UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions
:
- QueryStringRequestCultureProvider
- CookieRequestCultureProvider
- AcceptLanguageHeaderRequestCultureProvider
Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.
QueryStringRequestCultureProvider
Einige Apps verwenden eine Abfragezeichenfolge, um die CultureInfo festzulegen. 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. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider
registriert. Sie übergeben die Abfragezeichenfolge-Parameter culture
und ui-culture
. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
Wenn nur culture
oder nur ui-culture
übergeben wird, legt der Anbieter der Abfragezeichenfolge beide Werte auf den übergebenen Wert fest. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture
als auch UICulture
wie folgt festgelegt:
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.
CookieRequestCultureProvider DefaultCookieName gibt den Standardcookienamen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt. Der Standardcookiename lautet .AspNetCore.Culture
.
Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%
, wobei c
für Culture
steht und uic
für UICulture
, zum Beispiel:
c=en-UK|uic=en-US
Wenn nur die Kulturinformation oder nur die Benutzeroberflächenkultur verfügbar ist, wird die bereitgestellte Kultur sowohl für die Kulturinformation als auch für die Benutzeroberflächenkultur verwendet.
Der 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. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde. 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)). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.
Festlegen des Accept-Language-HTTP-Headers in Edge
Sucheinstellungen für bevorzugte Sprachen.
Die bevorzugten Sprachen sind im Feld Bevorzugte Sprachen aufgeführt.
Wählen Sie Sprachen hinzufügen aus, um sie der Liste hinzuzufügen.
Wählen Sie Weitere Aktionen ... neben einer Sprache aus, um die bevorzugte Reihenfolge zu ändern.
Der Content-Language-HTTP-Header
Der Content-Language-Entitätsheader:
- Wird verwendet, um die für die Zielgruppe vorgesehenen Sprachen zu beschreiben.
- Ermöglicht einem Benutzer, gemäß seiner bevorzugten Sprache zu differenzieren.
Entitätsheader werden in HTTP-Anforderungen und -Antworten verwendet.
Der Content-Language
-Header kann durch Festlegen der Eigenschaft ApplyCurrentCultureToResponseHeaders hinzugefügt werden.
Hinzufügen des Content-Language
-Headers:
- Ermöglicht RequestLocalizationMiddleware das Festlegen des
Content-Language
-Headers mitCurrentUICulture
. - Macht das explizite Festlegen des
Content-Language
-Antwortheaders überflüssig.
app.UseRequestLocalization(new RequestLocalizationOptions
{
ApplyCurrentCultureToResponseHeaders = true
});
Anwenden des RouteDataRequest CultureProviders
Die RouteDataRequestCultureProvider Kultur wird basierend auf dem Wert des culture
Routenwerts festgelegt. Informationen finden Sie unter URL-Kulturanbieter, der Middleware als Filter verwendet:
- Verwenden der Middleware als Filterfeature von ASP.NET Core.
- So verwenden Sie
RouteDataRequestCultureProvider
, um die Kultur einer App über die URL festzulegen.
Informationen zur globalen Anwendung des RouteDataRequest CultureProvider mit Middleware finden Sie unter „Anwenden des RouteDataRequest CultureProvider“ als FilterRouteDataRequestCultureProvider
.
Verwenden eines benutzerdefinierten Anbieters
Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:
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 await Task.FromResult(new ProviderCultureResult("en"));
}));
});
Verwenden Sie RequestLocalizationOptions
, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.
Ändern der Reihenfolge der Anforderungskulturanbieter
RequestLocalizationOptions hat drei Standardanbieter für Anforderungen der Kultur: QueryStringRequestCultureProvider, CookieRequestCultureProvider und AcceptLanguageHeaderRequestCultureProvider. Verwenden Sie die Eigenschaft RequestLocalizationOptions.RequestCultureProviders
, um die Reihenfolge dieser Anbieter wie unten gezeigt zu ändern:
app.UseRequestLocalization(options =>
{
var questStringCultureProvider = options.RequestCultureProviders[0];
options.RequestCultureProviders.RemoveAt(0);
options.RequestCultureProviders.Insert(1, questStringCultureProvider);
});
Im vorstehenden Beispiel ist die Reihenfolge von QueryStringRequestCultureProvider
und CookieRequestCultureProvider
umgestellt, sodass RequestLocalizationMiddleware
zuerst in den cookies und dann in der Abfragezeichenfolge nach den Kulturen sucht.
Wie bereits erwähnt, fügen Sie über AddInitialRequestCultureProvider einen benutzerdefinierten Anbieter hinzu, der die Reihenfolge auf 0
festlegt, sodass dieser Anbieter Vorrang vor den anderen hat.
Überschreiben der Kultur durch Benutzer*innen
Mit der Eigenschaft RequestLocalizationOptions.CultureInfoUseUserOverride kann die App festlegen, ob nicht standardmäßige Windows-Einstellungen für die Eigenschaften CultureInfo DateTimeFormat und NumberFormat verwendet werden sollen oder nicht. Dies hat in Linux keine Auswirkungen. Dies ist eine direkte Entsprechung von UseUserOverride.
app.UseRequestLocalization(options =>
{
options.CultureInfoUseUserOverride = false;
});
Programmgesteuertes Festlegen der Kultur
Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture
. Die Datei Views/Shared/_SelectLanguagePartial.cshtml
ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:
@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:
<div class="container body-content" style="margin-top:60px">
@RenderBody()
<hr>
<footer>
<div class="row">
<div class="col-md-6">
<p>© @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.
[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. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions
durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.
Routendaten und Abfragezeichenfolgen für die Modellbindung
Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.
Nächste Schritte
Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:
- Den Inhalt der App lokalisierbar machen.
- Bereitstellen der lokalisierten Ressourcen für die von der App unterstützten Sprachen und Kulturen
Zusätzliche Ressourcen
- URL-Kulturanbieter, der Middleware als Filter in ASP.NET Core verwendet
- Globales Anwenden von RouteDataRequest CultureProvider mit Middleware als Filter
- Globalisierung und Lokalisierung in ASP.NET Core
- Den Inhalt einer ASP.NET Core-App lokalisierbar machen
- Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App
- Problembehandlung bei der ASP.NET Core-Lokalisierung
- Globalisieren und Lokalisieren von .NET-Anwendungen
- Localization.StarterWeb-Projekt wird im Artikel verwendet.
- Ressourcen in RESX-Dateien
- Microsoft Multilingual App Toolkit
- Lokalisierung und Generics
Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana und Rick Anderson
Eine Aufgabe zum Lokalisieren einer App besteht darin, eine Strategie zum Auswählen der geeigneten Kultur für jede Antwort zu implementieren, die die App zurückgibt.
Konfigurieren der Lokalisierungsmiddleware
Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt. Die Middleware für die Lokalisierung wird in Program.cs
aktiviert. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z. B. app.UseMvcWithDefaultRoute()
).
builder.Services.Configure<RequestLocalizationOptions>(options =>
{
var supportedCultures = new[] { "en-US", "fr" };
options.SetDefaultCulture(supportedCultures[0])
.AddSupportedCultures(supportedCultures)
.AddSupportedUICultures(supportedCultures);
});
UseRequestLocalization initialisiert ein RequestLocalizationOptions-Objekt. Bei jeder Anforderung wird die Liste von RequestCultureProvider in RequestLocalizationOptions aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions
:
- QueryStringRequestCultureProvider
- CookieRequestCultureProvider
- AcceptLanguageHeaderRequestCultureProvider
Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture verwendet.
QueryStringRequestCultureProvider
Einige Apps verwenden eine Abfragezeichenfolge, um die CultureInfo festzulegen. 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. Standardmäßig ist QueryStringRequestCultureProvider als erster Lokalisierungsanbieter in der Liste RequestCultureProvider
registriert. Sie übergeben die Abfragezeichenfolge-Parameter culture
und ui-culture
. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
Wenn nur culture
oder nur ui-culture
übergeben wird, legt der Anbieter der Abfragezeichenfolge beide Werte auf den übergebenen Wert fest. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture
als auch UICulture
wie folgt festgelegt:
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies. Verwenden Sie die Methode MakeCookieValue zum Erstellen eines cookies.
xref:Microsoft.AspNetCore.Localization.CookieRequestCultureProvider>DefaultCookieName gibt den Standardnamen von cookie zurück, der zum Nachverfolgen der bevorzugten Kulturinformationen des Benutzers verwendet wird. Der Standardcookiename lautet .AspNetCore.Culture
.
Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%
, wobei c
für Culture
steht und uic
für UICulture
, zum Beispiel:
c=en-UK|uic=en-US
Wenn nur die Kulturinformation oder nur die Benutzeroberflächenkultur verfügbar ist, wird die bereitgestellte Kultur sowohl für die Kulturinformation als auch für die Benutzeroberflächenkultur verwendet.
Der 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. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde. 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)). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.
Festlegen des Accept-Language-HTTP-Headers in Edge
Sucheinstellungen für bevorzugte Sprachen.
Die bevorzugten Sprachen sind im Feld Bevorzugte Sprachen aufgeführt.
Wählen Sie Sprachen hinzufügen aus, um sie der Liste hinzuzufügen.
Wählen Sie Weitere Aktionen ... neben einer Sprache aus, um die bevorzugte Reihenfolge zu ändern.
Der Content-Language-HTTP-Header
Der Content-Language-Entitätsheader:
- Wird verwendet, um die für die Zielgruppe vorgesehenen Sprachen zu beschreiben.
- Ermöglicht einem Benutzer, gemäß seiner bevorzugten Sprache zu differenzieren.
Entitätsheader werden in HTTP-Anforderungen und -Antworten verwendet.
Der Content-Language
-Header kann durch Festlegen der Eigenschaft ApplyCurrentCultureToResponseHeaders hinzugefügt werden.
Hinzufügen des Content-Language
-Headers:
- Ermöglicht RequestLocalizationMiddleware das Festlegen des
Content-Language
-Headers mitCurrentUICulture
. - Macht das explizite Festlegen des
Content-Language
-Antwortheaders überflüssig.
app.UseRequestLocalization(new RequestLocalizationOptions
{
ApplyCurrentCultureToResponseHeaders = true
});
Verwenden eines benutzerdefinierten Anbieters
Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:
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 await Task.FromResult(new ProviderCultureResult("en"));
}));
});
Verwenden Sie RequestLocalizationOptions
, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.
Ändern der Reihenfolge der Anforderungskulturanbieter
RequestLocalizationOptions hat drei Standardanbieter für Anforderungen der Kultur: QueryStringRequestCultureProvider, CookieRequestCultureProvider und AcceptLanguageHeaderRequestCultureProvider. Verwenden Sie die Eigenschaft RequestLocalizationOptions.RequestCultureProviders
, um die Reihenfolge dieser Anbieter wie unten gezeigt zu ändern:
app.UseRequestLocalization(options =>
{
var questStringCultureProvider = options.RequestCultureProviders[0];
options.RequestCultureProviders.RemoveAt(0);
options.RequestCultureProviders.Insert(1, questStringCultureProvider);
});
Im vorstehenden Beispiel ist die Reihenfolge von QueryStringRequestCultureProvider
und CookieRequestCultureProvider
umgestellt, sodass RequestLocalizationMiddleware
zuerst in den cookies und dann in der Abfragezeichenfolge nach den Kulturen sucht.
Wie bereits erwähnt, fügen Sie über AddInitialRequestCultureProvider einen benutzerdefinierten Anbieter hinzu, der die Reihenfolge auf 0
festlegt, sodass dieser Anbieter Vorrang vor den anderen hat.
Programmgesteuertes Festlegen der Kultur
Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture
. Die Datei Views/Shared/_SelectLanguagePartial.cshtml
ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:
@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:
<div class="container body-content" style="margin-top:60px">
@RenderBody()
<hr>
<footer>
<div class="row">
<div class="col-md-6">
<p>© @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.
[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. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions
durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.
Routendaten und Abfragezeichenfolgen für die Modellbindung
Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.
Nächste Schritte
Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:
- Den Inhalt der App lokalisierbar machen.
- Bereitstellen der lokalisierten Ressourcen für die von der App unterstützten Sprachen und Kulturen
Zusätzliche Ressourcen
- Globalisierung und Lokalisierung in ASP.NET Core
- Den Inhalt einer ASP.NET Core-App lokalisierbar machen
- Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App
- Problembehandlung bei der ASP.NET Core-Lokalisierung
- Globalisieren und Lokalisieren von .NET-Anwendungen
- Localization.StarterWeb-Projekt wird im Artikel verwendet.
- Ressourcen in RESX-Dateien
- Microsoft Multilingual App Toolkit
- Lokalisierung und Generics
Von Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana, und Hisham Bin Ateya
Eine Aufgabe zum Lokalisieren einer App besteht darin, eine Strategie zum Auswählen der geeigneten Kultur für jede Antwort zu implementieren, die die App zurückgibt.
Konfigurieren der Lokalisierungsmiddleware
Die aktuell angefragte Kultur wird in der Middleware für die Lokalisierung festgelegt. Die Middleware für die Lokalisierung wird in der Startup.Configure
-Methode aktiviert. Die Lokalisierungsmiddleware muss vor Middleware konfiguriert werden, die möglicherweise die Anforderungskultur prüft (z. B. app.UseMvcWithDefaultRoute()
).
var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
.AddSupportedCultures(supportedCultures)
.AddSupportedUICultures(supportedCultures);
app.UseRequestLocalization(localizationOptions);
UseRequestLocalization
initialisiert ein RequestLocalizationOptions
-Objekt. Bei jeder Anforderung wird die Liste von RequestCultureProvider
in RequestLocalizationOptions
aufgelistet und der erste Anbieter, der erfolgreich die Anforderungskultur bestimmen kann, wird verwendet. Die Standardanbieter stammen aus der Klasse RequestLocalizationOptions
:
QueryStringRequestCultureProvider
CookieRequestCultureProvider
AcceptLanguageHeaderRequestCultureProvider
Die Reihenfolge der Standardliste fängt bei den spezifischsten Anbietern an und endet mit den allgemeinsten. Im Verlauf des Artikels erfahren Sie, wie Sie die Reihenfolge ändern und einen benutzerdefinierten Kulturanbieter hinzufügen. Wenn kein Anbieter die Anforderungskultur bestimmen kann, wird DefaultRequestCulture
verwendet.
QueryStringRequestCultureProvider
Einige Apps verwenden eine Abfragezeichenfolge, um die CultureInfo festzulegen. 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. Standardmäßig ist QueryStringRequestCultureProvider
als erster Lokalisierungsanbieter in der Liste RequestCultureProvider
registriert. Sie übergeben die Abfragezeichenfolge-Parameter culture
und ui-culture
. Im folgenden Beispiel ist die spezifische Kultur (Sprache und Region) auf Spanisch/Mexiko festgelegt:
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. Wenn beispielsweise nur die Kultur festgelegt wird, werden sowohl Culture
als auch UICulture
wie folgt festgelegt:
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Produktions-Apps bieten oft einen Mechanismus zum Festlegen der Kultur mithilfe des ASP.NET Core-Kulturcookies. Verwenden Sie die Methode MakeCookieValue
zum Erstellen eines cookies.
CookieRequestCultureProvider
DefaultCookieName
gibt den Standardcookienamen zurück, mit dem ermittelt wird, welche Kulturinformationen der Benutzer bevorzugt. Der Standardcookiename lautet .AspNetCore.Culture
.
Das cookieformat ist c=%LANGCODE%|uic=%LANGCODE%
, wobei c
für Culture
steht und uic
für UICulture
, zum Beispiel:
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.
Der 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. Diese Einstellung gibt an, was im Browser zum Senden festgelegt ist oder vom zugrunde liegenden Betriebssystem geerbt wurde. 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)). In einer Produktions-App sollten Benutzer die Möglichkeit haben, ihre bevorzugte Kultur anzupassen.
Festlegen des Accept-Language-HTTP-Headers in Edge
Sucheinstellungen für bevorzugte Sprachen.
Die bevorzugten Sprachen sind im Feld Bevorzugte Sprachen aufgeführt.
Wählen Sie Sprachen hinzufügen aus, um sie der Liste hinzuzufügen.
Wählen Sie Weitere Aktionen ... neben einer Sprache aus, um die bevorzugte Reihenfolge zu ändern.
Der Content-Language-HTTP-Header
Der Content-Language-Entitätsheader:
- Wird verwendet, um die für die Zielgruppe vorgesehenen Sprachen zu beschreiben.
- Ermöglicht einem Benutzer, gemäß seiner bevorzugten Sprache zu differenzieren.
Entitätsheader werden in HTTP-Anforderungen und -Antworten verwendet.
Der Content-Language
-Header kann durch Festlegen der Eigenschaft ApplyCurrentCultureToResponseHeaders
hinzugefügt werden.
Hinzufügen des Content-Language
-Headers:
- Ermöglicht RequestLocalizationMiddleware, den
Content-Language
-Header mit derCurrentUICulture
festzulegen. - Macht das explizite Festlegen des
Content-Language
-Antwortheaders überflüssig.
app.UseRequestLocalization(new RequestLocalizationOptions
{
ApplyCurrentCultureToResponseHeaders = true
});
Verwenden eines benutzerdefinierten Anbieters
Angenommen, Sie möchten Ihren Kunden das Speichern ihrer Sprache und Kultur in Ihren Datenbanken ermöglichen. In diesem Fall können Sie einen Anbieter codieren, der diese Werte für den Benutzer abruft. Im folgenden Codebeispiel wird veranschaulicht, wie Sie einen benutzerdefinierten Anbieter hinzufügen:
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 await Task.FromResult(new ProviderCultureResult("en"));
}));
});
Verwenden Sie RequestLocalizationOptions
, um Lokalisierungsanbieter hinzuzufügen oder zu entfernen.
Ändern der Reihenfolge der Anforderungskulturanbieter
RequestLocalizationOptions hat drei Standardanbieter für Anforderungen der Kultur: QueryStringRequestCultureProvider, CookieRequestCultureProvider und AcceptLanguageHeaderRequestCultureProvider. Verwenden Sie die Eigenschaft RequestLocalizationOptions.RequestCultureProviders
, um die Reihenfolge dieser Anbieter wie unten gezeigt zu ändern:
app.UseRequestLocalization(options =>
{
var questStringCultureProvider = options.RequestCultureProviders[0];
options.RequestCultureProviders.RemoveAt(0);
options.RequestCultureProviders.Insert(1, questStringCultureProvider);
});
Im vorstehenden Beispiel ist die Reihenfolge von QueryStringRequestCultureProvider
und CookieRequestCultureProvider
umgestellt, sodass RequestLocalizationMiddleware
zuerst in den cookies und dann in der Abfragezeichenfolge nach den Kulturen sucht.
Wie bereits erwähnt, fügen Sie über AddInitialRequestCultureProvider einen benutzerdefinierten Anbieter hinzu, der die Reihenfolge auf 0
festlegt, sodass dieser Anbieter Vorrang vor den anderen hat.
Programmgesteuertes Festlegen der Kultur
Das Beispielprojekt Localization.StarterWeb auf GitHub enthält eine Benutzeroberfläche zum Festlegen von Culture
. Die Datei Views/Shared/_SelectLanguagePartial.cshtml
ermöglicht Ihnen das Auswählen der Kultur aus der Liste von unterstützten Kulturen:
@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:
<div class="container body-content" style="margin-top:60px">
@RenderBody()
<hr>
<footer>
<div class="row">
<div class="col-md-6">
<p>© @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.
[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. Das Projekt Localization.StarterWeb auf GitHub enthält Code, der RequestLocalizationOptions
durch den Container von Dependency Injection an eineRazor-Teilansicht übermittelt.
Routendaten und Abfragezeichenfolgen für die Modellbindung
Weitere Informationen finden Sie unter Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die Modellbindung.
Nächste Schritte
Das Lokalisieren einer App umfasst zudem die folgenden Aufgaben:
- Den Inhalt der App lokalisierbar machen.
- Bereitstellen der lokalisierten Ressourcen für die von der App unterstützten Sprachen und Kulturen
Zusätzliche Ressourcen
- Globalisierung und Lokalisierung in ASP.NET Core
- Den Inhalt einer ASP.NET Core-App lokalisierbar machen
- Bereitstellen lokalisierter Ressourcen für Sprachen und Kulturen in einer ASP.NET Core-App
- Problembehandlung bei der ASP.NET Core-Lokalisierung
- Globalisieren und Lokalisieren von .NET-Anwendungen
- Localization.StarterWeb-Projekt wird im Artikel verwendet.
- Ressourcen in RESX-Dateien
- Microsoft Multilingual App Toolkit
- Lokalisierung und Generics
ASP.NET Core