Globalizace a lokalizace v ASP.NET Core
Poznámka:
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Upozorňující
Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Důležité
Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Aktuální verzi najdete ve verzi .NET 8 tohoto článku.
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana a Hisham Bin Ateya
Vícejazyčný web umožňuje, aby se web dostal k širšímu publiku. ASP.NET Core poskytuje služby a middleware pro lokalizaci do různých jazyků a jazykových verzí.
Termíny
- Globalizace (G11N): Proces vytvoření aplikace podporuje různé jazyky a oblasti. Zkratka pochází z prvních a posledních písmen a počtu písmen mezi nimi.
- Lokalizace (L10N): Proces přizpůsobení globalizované aplikace pro konkrétní jazyky a oblasti.
- Internationalizace (I18N): Globalizace i lokalizace.
- Jazyk: Jazyk a volitelně oblast.
- Neutrální jazyková verze: Jazyková verze, která má zadaný jazyk, ale ne oblast (například "en", "es").
- Konkrétní jazyková verze: Jazyková verze, která má zadaný jazyk a oblast (například en-US, en-GB, es-CL).
- Nadřazená jazyková verze: Neutrální jazyková verze, která obsahuje konkrétní jazykovou verzi (například "en" je nadřazená jazyková verze en-US a en-GB).
- Národní prostředí: Národní prostředí je stejné jako jazyková verze.
Kódy jazyka a země/oblasti
Formát RFC 4646 pro název jazykové verze je <language code>-<country/region code>
, kde <language code>
identifikuje jazyk a <country/region code>
identifikuje subculture. Například es-CL
pro španělštinu (Chile), en-US
pro angličtinu (USA) a en-AU
pro angličtinu (Austrálie). RFC 4646 je kombinací dvoumísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoumísmenného kódu subculture iso 3166 přidruženého k zemi nebo oblasti. Další informace najdete na webu System.Globalization.CultureInfo.
Úlohy pro lokalizaci aplikace
Globalizace a lokalizace aplikace zahrnuje následující úlohy:
- Nastavení lokalizovatelného obsahu aplikace ASP.NET Core
- Poskytnutí lokalizovaných prostředků pro jazykové verze, které aplikace podporuje
- Implementace strategie pro výběr jazykové verze pro jednotlivé požadavky
Zobrazení nebo stažení ukázkového kódu (postup stažení)
Další materiály
- Poskytovatel jazykové verze adresy URL, který používá middleware jako filtry v ASP.NET Core
- Globální použití RouteDataRequest CultureProvideru s middlewarem jako filtry
IStringLocalizer
: Používá ResourceManager prostředky ResourceReader specifické pro jazykovou verzi za běhu. Rozhraní má indexer a proIEnumerable
vrácení lokalizovaných řetězců.IHtmlLocalizer
: Pro prostředky, které obsahují kód HTML.- Zobrazení a poznámky k datům
- Řešení potíží s lokalizací ASP.NET Core
- Globalizace a lokalizace aplikací .NET
- Prostředky v souborech .resx
- Microsoft Multilingual App Toolkit
- Lokalizace a obecné typy
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana a Hisham Bin Ateya
Vícejazyčný web umožňuje, aby se web dostal k širšímu publiku. ASP.NET Core poskytuje služby a middleware pro lokalizaci do různých jazyků a jazykových verzí.
Termíny
- Globalizace (G11N): Proces vytvoření aplikace podporuje různé jazyky a oblasti. Zkratka pochází z prvních a posledních písmen a počtu písmen mezi nimi.
- Lokalizace (L10N): Proces přizpůsobení globalizované aplikace pro konkrétní jazyky a oblasti.
- Internationalizace (I18N): Globalizace i lokalizace.
- Jazyk: Jazyk a volitelně oblast.
- Neutrální jazyková verze: Jazyková verze, která má zadaný jazyk, ale ne oblast (například "en", "es").
- Konkrétní jazyková verze: Jazyková verze, která má zadaný jazyk a oblast (například en-US, en-GB, es-CL).
- Nadřazená jazyková verze: Neutrální jazyková verze, která obsahuje konkrétní jazykovou verzi (například "en" je nadřazená jazyková verze en-US a en-GB).
- Národní prostředí: Národní prostředí je stejné jako jazyková verze.
Kódy jazyka a země/oblasti
Formát RFC 4646 pro název jazykové verze je <language code>-<country/region code>
, kde <language code>
identifikuje jazyk a <country/region code>
identifikuje subculture. Například es-CL
pro španělštinu (Chile), en-US
pro angličtinu (USA) a en-AU
pro angličtinu (Austrálie). RFC 4646 je kombinací dvoumísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoumísmenného kódu subculture iso 3166 přidruženého k zemi nebo oblasti. Další informace najdete na webu System.Globalization.CultureInfo.
Úlohy pro lokalizaci aplikace
Globalizace a lokalizace aplikace zahrnuje následující úlohy:
- Nastavení lokalizovatelného obsahu aplikace ASP.NET Core
- Poskytnutí lokalizovaných prostředků pro jazykové verze, které aplikace podporuje
- Implementace strategie pro výběr jazykové verze pro jednotlivé požadavky
Zobrazení nebo stažení ukázkového kódu (postup stažení)
Další materiály
- Nastavení lokalizovatelného obsahu aplikace ASP.NET Core
- Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze v aplikaci ASP.NET Core
- Strategie pro výběr jazyka a jazykové verze v lokalizované aplikaci ASP.NET Core
- Řešení potíží s lokalizací ASP.NET Core
- Globalizace a lokalizace aplikací .NET
- Projekt Localization.StarterWeb použitý v článku
- Prostředky v souborech .resx
- Microsoft Multilingual App Toolkit
- Lokalizace a obecné typy
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana a Hisham Bin Ateya
Vícejazyčný web umožňuje, aby se web dostal k širšímu publiku. ASP.NET Core poskytuje služby a middleware pro lokalizaci do různých jazyků a jazykových verzí.
Internacionalizace zahrnuje System.Globalization a lokalizaci. Globalizace je proces návrhu aplikací, které podporují různé jazykové verze. Globalizace přidává podporu vstupu, zobrazení a výstupu definované sady skriptů jazyka, které souvisejí s konkrétními geografickými oblastmi.
Lokalizace je proces přizpůsobení globalizované aplikace, kterou jste už zpracovali pro lokalizovatelnost, na konkrétní jazykovou verzi nebo národní prostředí. Další informace naleznete v tématu Globalizace a termíny lokalizace na konci tohoto dokumentu.
Lokalizace aplikací zahrnuje následující:
- Nastavení lokalizovatelného obsahu aplikace
- Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze, které podporujete
- Implementace strategie pro výběr jazyka a jazykové verze pro každý požadavek
Zobrazení nebo stažení ukázkového kódu (postup stažení)
Nastavení lokalizovatelného obsahu aplikace
IStringLocalizer byly IStringLocalizer<T> navrženy tak, aby zlepšily produktivitu při vývoji lokalizovaných aplikací. IStringLocalizer
ResourceManager používá prostředky ResourceReader specifické pro jazykovou verzi za běhu. Rozhraní má indexer a pro IEnumerable
vrácení lokalizovaných řetězců. IStringLocalizer
nevyžaduje uložení výchozích řetězců jazyka do souboru prostředků. Můžete vyvíjet aplikaci určenou pro lokalizaci a nemusíte vytvářet soubory prostředků v rané fázi vývoje. Následující kód ukazuje, jak zabalit řetězec "O názvu" pro lokalizaci.
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"];
}
}
}
V předchozím kódu IStringLocalizer<T>
pochází implementace z injektáže závislostí. Pokud se lokalizovaná hodnota "O názvu" nenajde, vrátí se klíč indexeru, tj. řetězec "O názvu". V aplikaci můžete ponechat výchozí řetězce literálů jazyka a zabalit je do lokalizátoru, abyste se mohli soustředit na vývoj aplikace. Aplikaci vyvíjíte s výchozím jazykem a připravíte ji na krok lokalizace, aniž byste nejdřív vytvořili výchozí soubor prostředků. Případně můžete použít tradiční přístup a zadat klíč k načtení výchozího řetězce jazyka. Pro mnoho vývojářů nový pracovní postup, který nemá výchozí soubor .resx jazyka a jednoduše zabalit řetězcové literály, může snížit režii při lokalizaci aplikace. Jiní vývojáři budou preferovat tradiční pracovní postup, protože může usnadnit práci s delšími řetězcovými literály a usnadnit aktualizaci lokalizovaných řetězců.
Použijte implementaci IHtmlLocalizer<T>
pro prostředky, které obsahují kód HTML. IHtmlLocalizer
KÓD HTML kóduje argumenty, které jsou formátovány v řetězci prostředku, ale nezakóduje samotný řetězec prostředku HTML. V ukázce zvýrazněné níže je kódována pouze hodnota parametru name
HTML.
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();
}
Poznámka:
Obecně platí, že pouze lokalizujete text, nikoli HTML.
Na nejnižší úrovni se můžete IStringLocalizerFactory
dostat z injektáže závislostí:
{
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."];
Výše uvedený kód ukazuje jednotlivé metody vytvoření továrny.
Lokalizované řetězce můžete rozdělit podle kontroleru, oblasti nebo jen jednoho kontejneru. V ukázkové aplikaci se pro sdílené prostředky používá fiktivní třída s názvem SharedResource
.
// Dummy class to group shared resources
namespace Localization
{
public class SharedResource
{
}
}
Někteří vývojáři používají Startup
třídu k zahrnutí globálních nebo sdílených řetězců. V následující InfoController
ukázce se používají místní a SharedResource
místní proměnné:
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;
}
Zobrazit lokalizaci
Služba IViewLocalizer
poskytuje lokalizované řetězce pro zobrazení. Třída ViewLocalizer
implementuje toto rozhraní a najde umístění prostředku z cesty k souboru zobrazení. Následující kód ukazuje, jak použít výchozí implementaci 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>
Výchozí implementace IViewLocalizer
najde soubor prostředků na základě názvu souboru zobrazení. Není možné použít globální sdílený soubor prostředků. ViewLocalizer
implementuje lokalizátor pomocí IHtmlLocalizer
, takže Razor html kóduje lokalizovaný řetězec. Můžete parametrizovat řetězce prostředků a IViewLocalizer
kódovat parametry HTML, ale ne řetězec prostředku. Vezměte v úvahu následující Razor kód:
@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]
Soubor francouzského prostředku může obsahovat následující:
Key | Hodnota |
---|---|
<i>Hello</i> <b>{0}!</b> |
<i>Bonjour</i> <b>{0} !</b> |
Vykreslené zobrazení by obsahovalo kód HTML ze souboru prostředků.
Poznámka:
Obecně platí, že pouze lokalizujete text, nikoli HTML.
Pokud chcete použít sdílený soubor prostředků v zobrazení, zadejte 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>
Lokalizace dataAnnotations
Chybové zprávy DataAnnotations jsou lokalizovány s IStringLocalizer<T>
. Pomocí této možnosti ResourcesPath = "Resources"
lze chybové zprávy uložit do RegisterViewModel
některé z následujících cest:
- Prostředky/ViewModels.Account.RegisterViewModel.fr.resx
- Prostředky/ 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; }
}
Atributy bez ověření jsou lokalizovány.
Použití jednoho řetězce prostředků pro více tříd
Následující kód ukazuje, jak použít jeden řetězec prostředku pro ověřovací atributy s více třídami:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.AddDataAnnotationsLocalization(options => {
options.DataAnnotationLocalizerProvider = (type, factory) =>
factory.Create(typeof(SharedResource));
});
}
V předchozím kódu je třída odpovídající resxu, SharedResource
kde jsou uloženy ověřovací zprávy. Při tomto přístupu budou DataAnnotations používat SharedResource
pouze místo prostředku pro každou třídu.
Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze, které podporujete
SupportedCultures a SupportedUICultures
ASP.NET Core umožňuje zadat dvě hodnoty SupportedCultures jazykové verze a SupportedUICultures. Objekt CultureInfo určuje SupportedCultures
výsledky funkcí závislých na jazykové verzi, jako je datum, čas, číslo a formátování měny. SupportedCultures
určuje také pořadí řazení textu, konvencí velikosti písmen a porovnání řetězců. Další informace o tom, jak server získá jazykovou verzi, naleznete CultureInfo.CurrentCulture a CultureInfo.CurrentUICulture. Určuje SupportedUICultures
, které přeložené řetězce (ze .resx
souborů) vyhledá ResourceManager. Vyhledá ResourceManager
řetězce specifické pro jazykovou verzi, které jsou určeny CurrentUICulture
. Každé vlákno v .NET má CurrentCulture
a CurrentUICulture
objekty. Architektura tyto hodnoty kontroluje při vykreslování funkcí závislých na jazykové verzi. Pokud je jazyková verze aktuálního vlákna nastavena na en-US
(angličtina, USA), DateTime.Now.ToLongDateString()
zobrazí ; Thursday, February 18, 2016
pokud je ale CurrentCulture
nastavena na es-ES
(španělština, Španělsko), výstup je jueves, 18 de febrero de 2016
.
Soubory prostředků
Soubor prostředků je užitečný mechanismus pro oddělení lokalizovatelných řetězců od kódu. Přeložené řetězce pro jiný než výchozí jazyk jsou izolované v souborech prostředků .resx . Můžete například chtít vytvořit soubor prostředků španělštiny s názvem Welcome.es.resx obsahující přeložené řetězce. "es" je kód jazyka pro španělštinu. Vytvoření tohoto souboru prostředků v sadě Visual Studio:
V Průzkumník řešení klikněte pravým tlačítkem na složku, která bude obsahovat soubor> prostředků Přidat>novou položku.
Do pole Prohledat nainstalované šablony zadejte "prostředek" a pojmenujte soubor.
Do sloupce Název zadejte hodnotu klíče (nativní řetězec) a přeložený řetězec ve sloupci Hodnota.
Visual Studio zobrazuje soubor Welcome.es.resx .
Pojmenování souboru prostředků
Prostředky jsou pojmenovány pro úplný název typu jejich třídy minus název sestavení. Například francouzský zdroj v projektu, jehož hlavní sestavení je LocalizationWebsite.Web.dll
pro třídu LocalizationWebsite.Web.Startup
, by mělo mít název Startup.fr.resx. Prostředek pro třídu LocalizationWebsite.Web.Controllers.HomeController
by se jmenoval Controllers.HomeController.fr.resx. Pokud obor názvů cílové třídy není stejný jako název sestavení, budete potřebovat úplný název typu. Například v ukázkovém projektu by byl zdroj pro typ ExtraNamespace.Tools
pojmenován ExtraNamespace.Tools.fr.resx.
V ukázkovém projektu metoda ConfigureServices
nastaví ResourcesPath
hodnotu "Resources", takže relativní cesta k projektu pro soubor francouzského zdrojového souboru domovského kontroleru je Resources/Controllers.HomeController.fr.resx. Případně můžete pomocí složek uspořádat soubory prostředků. Pro domácí kontroler by cesta byla Resources/Controllers/HomeController.fr.resx. Pokud tuto možnost nepoužíváte ResourcesPath
, soubor .resx přejde do základního adresáře projektu. Soubor prostředků by HomeController
se jmenoval Kontrolery.HomeController.fr.resx. Volba použití konvence pojmenování tečky nebo cesty závisí na tom, jak chcete uspořádat soubory prostředků.
Název prostředku | Pojmenování tečky nebo cesty |
---|---|
Prostředky/kontrolery.HomeController.fr.resx | Tečka |
Prostředky/ Kontrolery/HomeController.fr.resx | Cesta |
Soubory prostředků, které se používají @inject IViewLocalizer
v Razor zobrazeních, se řídí podobným vzorem. Soubor prostředků pro zobrazení lze pojmenovat pomocí pojmenování tečky nebo pojmenování cesty. Razor Zobrazit soubory prostředků napodobují cestu k přidruženému souboru zobrazení. Za předpokladu ResourcesPath
, že nastavíme hodnotu "Zdroje", soubor francouzského prostředku přidružený k Views/Home/About.cshtml
zobrazení může být některý z následujících:
Prostředky/Views/Home/About.fr.resx
Prostředky/zobrazení.Home. About.fr.resx
Pokud tuto možnost nepoužíváte ResourcesPath
, soubor .resx pro zobrazení by byl umístěn ve stejné složce jako zobrazení.
RootNamespaceAttribute
Atribut RootNamespaceAttribute poskytuje kořenový obor názvů sestavení, pokud je kořenový obor názvů sestavení jiný než název sestavení.
Upozorňující
K tomu může dojít v případě, že název projektu není platný identifikátor .NET. Například my-project-name.csproj
použije kořenový obor názvů my_project_name
a název my-project-name
sestavení vedoucí k této chybě.
Pokud se kořenový obor názvů sestavení liší od názvu sestavení:
- Lokalizace ve výchozím nastavení nefunguje.
- Lokalizace selže kvůli způsobu hledání prostředků v rámci sestavení.
RootNamespace
je hodnota času sestavení, která není k dispozici pro provádění procesu.
RootNamespace
Pokud se liší od AssemblyName
hodnoty , zahrňte následující hodnoty AssemblyInfo.cs
(s hodnotami parametrů nahrazenými skutečnými hodnotami):
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Předchozí kód umožňuje úspěšné rozlišení souborů resx.
Záložní chování jazykové verze
Při hledání prostředku se lokalizace zabývá "záložní verzí". Počínaje požadovanou jazykovou verzí, pokud nebyla nalezena, vrátí se k nadřazené jazykové verzi této jazykové verze. Kromě toho CultureInfo.Parent vlastnost představuje nadřazenou jazykovou verzi. To obvykle (ale ne vždy) znamená odebrání národního signifikátoru z ISO. Například dialekt španělštiny mluveného v Mexiku je "es-MX". Má nadřazenou "es" – španělštinu nespecisovat pro libovolnou zemi.
Představte si, že váš web obdrží požadavek na "uvítací" prostředek pomocí jazykové verze "fr-CA". Lokalizační systém hledá následující prostředky v pořadí a vybere první shodu:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (pokud
NeutralResourcesLanguage
je "fr-CA")
Pokud například odeberete designátor jazykové verze ".fr" a máte jazykovou verzi nastavenou na francouzštinu, výchozí soubor prostředků se přečte a řetězce jsou lokalizované. Správce prostředků určí výchozí nebo záložní prostředek, pokud nic nesplňuje vaši požadovanou jazykovou verzi. Pokud chcete jen vrátit klíč, když chybí prostředek pro požadovanou jazykovou verzi, nesmíte mít výchozí soubor prostředků.
Generování souborů prostředků pomocí sady Visual Studio
Pokud v sadě Visual Studio vytvoříte soubor prostředků bez jazykové verze v názvu souboru (například Welcome.resx), Visual Studio vytvoří třídu jazyka C# s vlastností každého řetězce. To obvykle s ASP.NET Core nechcete. Obvykle nemáte výchozí soubor prostředků .resx ( soubor .resx bez názvu jazykové verze). Doporučujeme vytvořit soubor .resx s názvem jazykové verze (například Welcome.fr.resx). Když vytvoříte soubor .resx s názvem jazykové verze, Visual Studio vygeneruje soubor třídy.
Přidání dalších jazykových verzí
Každá kombinace jazyka a jazykové verze (kromě výchozího jazyka) vyžaduje jedinečný soubor prostředků. Soubory prostředků pro různé jazykové verze a národní prostředí vytvoříte vytvořením nových souborů prostředků, ve kterých jsou kódy jazyka ISO součástí názvu souboru (například en-us, fr-ca a en-gb). Tyto kódy ISO jsou umístěny mezi názvem souboru a příponou souboru .resx , jak je uvedeno v Welcome.es-MX.resx (španělština/Mexiko).
Implementace strategie pro výběr jazyka a jazykové verze pro každý požadavek
Konfigurace lokalizace
Lokalizace se konfiguruje v Startup.ConfigureServices
metodě:
services.AddLocalization(options => options.ResourcesPath = "Resources");
services.AddMvc()
.AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
.AddDataAnnotationsLocalization();
AddLocalization
přidá lokalizační služby do kontejneru služeb. Výše uvedený kód také nastaví cestu k prostředkům na "Resources".AddViewLocalization
přidává podporu lokalizovaných souborů zobrazení. V této ukázkové lokalizaci zobrazení je založená na příponě souboru zobrazení. Například "fr" vIndex.fr.cshtml
souboru.AddDataAnnotationsLocalization
přidává podporu lokalizovanýchDataAnnotations
ověřovacích zpráv prostřednictvímIStringLocalizer
abstrakcí.
Middleware lokalizace
Aktuální jazyková verze požadavku je nastavená v middlewaru lokalizace. V metodě je povolený Startup.Configure
middleware lokalizace. Middleware lokalizace musí být nakonfigurovaný před jakýmkoli middlewarem, který může zkontrolovat jazykovou verzi požadavku (například app.UseMvcWithDefaultRoute()
). Lokalizační middleware se musí objevit po směrování Middleware, pokud používáte RouteDataRequestCultureProvider. Další informace o pořadí middlewaru najdete v tématu ASP.NET Core Middleware.
var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
.AddSupportedCultures(supportedCultures)
.AddSupportedUICultures(supportedCultures);
app.UseRequestLocalization(localizationOptions);
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
UseRequestLocalization
inicializuje RequestLocalizationOptions
objekt. Na každém požadavku je seznam výčtu RequestCultureProvider
RequestLocalizationOptions
a první zprostředkovatel, který může úspěšně určit jazykovou verzi požadavku. Výchozí zprostředkovatelé pocházejí z RequestLocalizationOptions
třídy:
QueryStringRequestCultureProvider
CookieRequestCultureProvider
AcceptLanguageHeaderRequestCultureProvider
Výchozí seznam pochází od nejvýraznějšího po nejpodobnější. Později v článku se dozvíte, jak můžete změnit pořadí a dokonce přidat vlastního poskytovatele jazykové verze. Pokud žádný z poskytovatelů nemůže určit jazykovou verzi požadavku, použije se DefaultRequestCulture
.
QueryStringRequestCultureProvider
Některé aplikace budou k nastavení CultureInfořetězce dotazu používat řetězec dotazu . Pro aplikace, které používají přístup hlavičky cookie Nebo Accept-Language, je přidání řetězce dotazu na adresu URL užitečné pro ladění a testování kódu. Ve výchozím nastavení je zaregistrovaný QueryStringRequestCultureProvider
jako první zprostředkovatel lokalizace v RequestCultureProvider
seznamu. Předáte parametry culture
řetězce dotazu a ui-culture
. Následující příklad nastaví konkrétní jazykovou verzi (jazyk a oblast) na španělštinu nebo Mexiko:
http://localhost:5000/?culture=es-MX&ui-culture=es-MX
Pokud předáte pouze jednu ze dvou (culture
nebo ui-culture
), poskytovatel řetězce dotazu nastaví obě hodnoty pomocí hodnoty, kterou jste předali. Například nastavení pouze jazykové verze nastaví Culture
obě verze a UICulture
:
http://localhost:5000/?culture=es-MX
CookieRequestCultureProvider
Produkční aplikace často poskytují mechanismus nastavení jazykové verze s jazykovou verzí ASP.NET Core cookie. Použijte metodu MakeCookieValue
cookiek vytvoření .
Vrátí CookieRequestCultureProvider
DefaultCookieName
výchozí cookie název použitý ke sledování upřednostňovaných informací o jazykové verzi uživatele. Výchozí cookie název je .AspNetCore.Culture
.
Formát cookie je c=%LANGCODE%|uic=%LANGCODE%
, kde c
je Culture
a uic
je UICulture
, například:
c=en-UK|uic=en-US
Pokud zadáte jenom jednu z informací o jazykové verzi a jazykové verzi uživatelského rozhraní, použije se zadaná jazyková verze pro informace o jazykové verzi i jazykovou verzi uživatelského rozhraní.
Hlavička HTTP jazyka Accept
Hlavička Accept-Language je ve většině prohlížečů nastavená a původně byla určena k určení jazyka uživatele. Toto nastavení označuje, co byl prohlížeč nastavený tak, aby odesílal nebo zdědil ze základního operačního systému. Hlavička HTTP jazyka Accept-Language z požadavku prohlížeče není nechtěným způsobem, jak rozpoznat upřednostňovaný jazyk uživatele (viz Nastavení jazykových předvoleb v prohlížeči). Produkční aplikace by měla obsahovat způsob, jak si uživatel přizpůsobit svou volbu jazykové verze.
Nastavení hlavičky HTTP jazyka Accept-Language v IE
Z ikony ozubeného kola klepněte na Možnosti internetu.
Klepněte na Jazyky.
Klepněte na Nastavit jazykové předvolby.
Klepněte na Přidat jazyk.
Přidejte jazyk.
Klepněte na jazyk a potom klepněte na Přesunout nahoru.
Použití vlastního zprostředkovatele
Předpokládejme, že chcete zákazníkům umožnit ukládat jejich jazyk a kulturu do databází. Můžete napsat zprostředkovatele, který vyhledá tyto hodnoty pro uživatele. Následující kód ukazuje, jak přidat vlastního zprostředkovatele:
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"));
}));
});
Slouží RequestLocalizationOptions
k přidání nebo odebrání zprostředkovatelů lokalizace.
Změna pořadí poskytovatelů jazykové verze žádosti
RequestLocalizationOptions má tři výchozí poskytovatele jazykové verze žádostí: QueryStringRequestCultureProvider, CookieRequestCultureProvidera AcceptLanguageHeaderRequestCultureProvider. Pomocí vlastnosti [RequestLocalizationOptions.RequestCultureProviders
]](xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions.RequestCultureProviders) změňte pořadí těchto zprostředkovatelů, jak je znázorněno níže:
app.UseRequestLocalization(options =>
{
var questStringCultureProvider = options.RequestCultureProviders[0];
options.RequestCultureProviders.RemoveAt(0);
options.RequestCultureProviders.Insert(1, questStringCultureProvider);
});
V předchozím příkladu je pořadí QueryStringRequestCultureProvider
a CookieRequestCultureProvider
je přepnuto, takže RequestLocalizationMiddleware
hledá jazykové verze z cookieprvního řetězce dotazu.
Jak jsme už zmínili, přidejte vlastního zprostředkovatele, který AddInitialRequestCultureProvider nastaví pořadí na 0
, takže tento zprostředkovatel má přednost před ostatními.
Nastavení jazykové verze prostřednictvím kódu programu
Tento ukázkový projekt Localization.StarterWeb na GitHubu Culture
obsahuje uživatelské rozhraní pro nastavení . Soubor Views/Shared/_SelectLanguagePartial.cshtml
umožňuje vybrat jazykovou verzi ze seznamu podporovaných jazykových verzí:
@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>
Soubor Views/Shared/_SelectLanguagePartial.cshtml
se přidá do footer
části souboru rozložení, takže bude k dispozici pro všechna zobrazení:
<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>
Metoda SetLanguage
nastaví jazykovou verzi 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);
}
Ukázkový kód pro tento projekt se nedá připojit _SelectLanguagePartial.cshtml
. Projekt Localization.StarterWeb na GitHubu má kód pro tok do RequestLocalizationOptions
Razor částečné části prostřednictvím kontejneru injektáže závislostí.
Vazba modelu směruje data a řetězce dotazů
Viz Chování globalizace vazby modelu směrovat data a řetězce dotazů.
Termíny globalizace a lokalizace
Proces lokalizace aplikace také vyžaduje základní znalost relevantních znakových sad, které se běžně používají při vývoji moderního softwaru, a pochopení problémů souvisejících s nimi. I když všechny počítače ukládají text jako čísla (kódy), různé systémy ukládají stejný text pomocí různých čísel. Proces lokalizace odkazuje na překlad uživatelského rozhraní aplikace pro konkrétní jazykovou verzi nebo národní prostředí.
Lokalizovatelnost je zprostředkující proces pro ověření, že globalizovaná aplikace je připravená na lokalizaci.
Formát RFC 4646 pro název jazykové verze je <languagecode2>-<country/regioncode2>
, kde <languagecode2>
je kód jazyka a <country/regioncode2>
je subculture kód. Například es-CL
pro španělštinu (Chile), en-US
pro angličtinu (USA) a en-AU
pro angličtinu (Austrálie). RFC 4646 je kombinací dvoumísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoumísmenného kódu subculture iso 3166 přidruženého k zemi nebo oblasti. Další informace najdete na webu System.Globalization.CultureInfo.
Internationalizace se často zkracuje na "I18N". Zkratka přebírá první a poslední písmena a počet písmen mezi nimi, takže 18 představuje počet písmen mezi prvním písmenem "I" a posledním písmenem "N". Totéž platí pro globalizaci (G11N) a lokalizaci (L10N).
Termíny:
- Globalizace (G11N): Proces vytvoření aplikace podporuje různé jazyky a oblasti.
- Lokalizace (L10N): Proces přizpůsobení aplikace pro daný jazyk a oblast.
- Internationalization (I18N): Popisuje globalizaci i lokalizaci.
- Jazyk: Jedná se o jazyk a volitelně i oblast.
- Neutrální jazyková verze: Jazyková verze, která má zadaný jazyk, ale ne oblast. (například "en", "es")
- Konkrétní jazyková verze: Jazyková verze, která má zadaný jazyk a oblast. (například "en-US", "en-GB", "es-CL")
- Nadřazená jazyková verze: Neutrální jazyková verze, která obsahuje konkrétní jazykovou verzi. (například "en" je nadřazená jazyková verze "en-US" a "en-GB")
- Národní prostředí: Národní prostředí je stejné jako jazyková verze.
Poznámka:
V desetinných polích možná nebudete moct zadávat desetinné čárky. Pokud chcete podporovat ověřování jQuery pro neanglické národní prostředí, které používají čárku (",") pro desetinnou čárku a jiné formáty kalendářních dat než v angličtině, musíte provést kroky ke globalizaci aplikace. Pokyny k přidání desetinné čárky najdete v tomto komentáři GitHubu 4076 .
Poznámka:
Před ASP.NET Core 3.0 webové aplikace zapisují jeden protokol typu LogLevel.Warning
na požadavek, pokud požadovaná jazyková verze není podporována. Protokolováním jedné LogLevel.Warning
žádosti můžete vytvořit velké soubory protokolů s redundantními informacemi. Toto chování se v ASP.NET 3.0 změnilo. Zapíše RequestLocalizationMiddleware
protokol typu LogLevel.Debug
, který zmenšuje velikost produkčních protokolů.