Globalizace a lokalizace v ASP.NET Core

Note

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 10 tohoto článku.

Warning

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete ve verzi .NET 10 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í.

Pokyny Blazor k lokalizaci, které doplňují nebo nahrazují pokyny uvedené v tomto článku, najdete v části globalizace a lokalizace v ASP.NET CoreBlazor.

Terms

  • 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.
  • Kultura: Jazyk a volitelně oblast.
  • Neutrální kultura: Kultura, která má určený jazyk, ale nikoli 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á kultura: Neutrální kultura, která obsahuje konkrétní kulturu (například "en" je nadřazená kultura "en-US" a "en-GB").
  • Národní prostředí: Národní prostředí je stejné jako nastavení regionu.

Kódy jazyka a země/oblasti

Formát RFC 4646 pro název kultury je <language code>-<country/region code>, kde <language code> identifikuje jazyk a <country/region code> identifikuje subkulturu. 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í dvoupísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoupísmenného kódu subkultury ISO 3166 ve verzálkách 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:

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Dodatečné zdroje

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í.

Terms

  • 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.
  • Kultura: Jazyk a případně oblast.
  • Neutrální jazyková kultura: Kultura, která má určený 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á kultura: Neutrální kultura, která obsahuje konkrétní kulturu (například "en" je nadřazená kultura "en-US" a "en-GB").
  • Národní prostředí: Národní prostředí je stejné jako nastavení regionu.

Kódy jazyka a země/oblasti

Formát RFC 4646 pro název kultury je <language code>-<country/region code>, kde <language code> identifikuje jazyk a <country/region code> identifikuje subkulturu. 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í dvoupísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoupísmenného kódu subkultury ISO 3166 ve verzálkách 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:

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Dodatečné zdroje

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í:

  1. Nastavení lokalizovatelného obsahu aplikace
  2. Poskytněte lokalizované prostředky pro jazyky a kultury, které podporujete
  3. Implementovat strategii pro výběr jazyka/kultury pro každý požadavek

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Nastavení lokalizovatelného obsahu aplikace

IStringLocalizer a IStringLocalizer<T> byly navrženy ke zlepšení produktivity při vývoji lokalizovaných aplikací. IStringLocalizer používá ResourceManager a ResourceReader k poskytování prostředků specifických pro jazykovou verzi za běhu. Rozhraní má indexer a IEnumerable, který slouží k vracení lokalizovaných řetězců. IStringLocalizer nevyžaduje uložení řetězců výchozího 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 zahrnout řetězec "About Title" 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 pochází IStringLocalizer<T> implementace ze závislostní injektáže. Pokud se nenajde lokalizovaná hodnota "About Title", vrátí se klíč indexeru, tedy řetězec "About Title". 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 HTML kóduje argumenty, které jsou formátovány v řetězci prostředku, ale samotný řetězec prostředku HTML nekóduje. 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();
        }

Note

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ím příkladu se používají lokalizátory InfoController a SharedResource:

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 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 nekó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 značení:

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

Soubor francouzského prostředku může obsahovat následující:

Key Value
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

Vykreslené zobrazení by obsahovalo kód HTML ze souboru zdrojů.

Note

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 datových anotací

Chybové zprávy DataAnnotations jsou lokalizovány s IStringLocalizer<T>. S možností ResourcesPath = "Resources" mohou být chybové zprávy v RegisterViewModel uloženy do některé z následujících cest:

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

Neověřovací atributy 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 zdrojový řetězec pro ověřovací atributy pro více tříd:

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 SharedResource odpovídající souboru resx, kde jsou uloženy ověřovací zprávy. Při tomto přístupu budou DataAnnotations používat pouze SharedResource místo prostředku pro každou třídu.

Poskytněte lokalizované prostředky pro jazyky a kultury, které podporujete

Podporované kultury a podporované UI kultury

ASP.NET Core umožňuje zadat dvě hodnoty jazykové verze, SupportedCultures a SupportedUICultures. Objekt CultureInfo určuje výsledky funkcí závislých na kultuře, 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 zjistí kulturu, viz CultureInfo.CurrentCulture a CultureInfo.CurrentUICulture. Určuje SupportedUICultures , které přeložené řetězce (ze .resx souborů) vyhledá ResourceManager. Vyhledá řetězce specifické pro kulturu, které jsou určeny CurrentUICulture. Každé vlákno v .NET má CurrentCulture a CurrentUICulture objekty. Rámec tyto hodnoty kontroluje při vykreslování funkcí závislých na kultuře. 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 uložené 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. Chcete-li vytvořit tento soubor zdrojů v aplikaci Visual Studio:

  1. V Průzkumníku řešení klikněte pravým tlačítkem myši na složku, která bude obsahovat soubor zdroje, >Přidat>Nová položka.

    Vnořená kontextová nabídka: V Průzkumníku řešení je otevřená kontextová nabídka pro prostředky. Je otevřena druhá kontextová nabídka pro možnost Přidat se zvýrazněným příkazem Nová položka.

  2. Do pole Prohledat nainstalované šablony zadejte "prostředek" a pojmenujte soubor.

    Dialogové okno Přidat novou položku

  3. Do sloupce Název zadejte hodnotu klíče (nativní řetězec) a přeložený řetězec ve sloupci Hodnota.

    Soubor Welcome.es.resx (uvítací soubor prostředku pro španělštinu) se slovem Hello ve sloupci Název a slovem Hola (Hello ve španělštině) ve sloupci Hodnota

    Visual Studio zobrazuje soubor Welcome.es.resx .

    Průzkumník řešení zobrazující soubor prostředků Welcome Spanish (es)

Pojmenování souboru zdrojů

Prostředky jsou pojmenovány podle úplného názvu typu jejich třídy bez názvu 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 na "Resources", takže relativní cesta k projektu pro soubor francouzských zdrojů domovského kontroleru je Resources/Controllers.HomeController.fr.resx. Případně můžete pomocí složek uspořádat soubory zdrojů. Pro domácí řadič 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ů HomeController by se jmenoval Controllers.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
Resources/Controllers.HomeController.fr.resx Dot
Resources/Controllers/HomeController.fr.resx Path

Soubory prostředků používané @inject IViewLocalizer v Razor zobrazeních řídí se podobným vzorem. Soubor prostředků pro zobrazení lze pojmenovat pomocí pojmenování tečky nebo pojmenování cesty. Razor Soubory prostředků napodobují cestu ke svému přidruženému souboru zobrazení. Pokud nastavíme ResourcesPath na "Zdroje", francouzský soubor zdrojů přidružený k zobrazení Views/Home/About.cshtml může být jedním 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í.

Warning

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 sestavení my-project-name, což vede k této chybě.

Pokud se kořenový obor názvů sestavení odlišuje od názvu sestavení:

  • Lokalizace ve výchozím nastavení nefunguje.
  • Lokalizace selže kvůli způsobu, jakým jsou prostředky hledány v rámci sestavení. RootNamespace je hodnota určená při sestavení, která není k dispozici pro spuštění procesu.

Pokud se RootNamespace liší od AssemblyName, zahrňte následující do AssemblyInfo.cs (při nahrazení hodnot parametrů 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.

Mechanismus záložní jazykové kultury

Při hledání prostředku se lokalizace zabývá "náhradní verzí kultury". Počínaje požadovanou kulturou, pokud není nalezena, vrátí se k nadřazené kultuře této kultury. Mimochodem, CultureInfo.Parent vlastnost představuje nadřazenou kulturu. 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řazený kód "es" – španělština neurčená pro konkrétní 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 následujícím pořadí a vybere první shodu:

  • Welcome.fr-CA.resx
  • Welcome.fr.resx
  • Welcome.resx (pokud NeutralResourcesLanguage je "fr-CA")

Pokud například odeberete označení kultury ".fr" a máte nastavenou kulturu na francouzštinu, výchozí soubor prostředků se přečte a řetězce jsou lokalizované. Správce zdrojů určí výchozí nebo záložní zdroj, když žádný neodpovídá vaší požadované jazykové verzi. Pokud chcete vrátit pouze klíč, když chybí prostředek pro požadovanou kulturní verzi, nesmíte mít výchozí soubor prostředků.

Generování souborů prostředků ve Visual Studio

Pokud v sadě Visual Studio vytvoříte soubor prostředků bez uvedení jazykové verze v názvu souboru (například Welcome.resx), Visual Studio vygeneruje třídu jazyka C# s vlastností pro každý řetězec. To obvykle s ASP.NET Core nechcete. Obvykle nemáte výchozí resx soubor (resx soubor 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 kultury, Visual Studio nevygeneruje soubor třídy.

Přidat další kultury

Každá kombinace jazyka a kultury (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).

Implementovat strategii pro výběr jazyka/kultury 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 tomto ukázkovém zobrazení je lokalizace založená na příponě názvu souboru zobrazení. Například "fr" v Index.fr.cshtml souboru.

  • AddDataAnnotationsLocalization přidává podporu lokalizovaných DataAnnotations ověřovacích zpráv prostřednictvím IStringLocalizer abstrakcí.

Lokalizační middleware

Aktuální nastavení kultury na žádosti je nastavené v lokalizačním middlewaru. V metodě je zapnuto middleware Startup.Configure pro lokalizaci. 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ěrovacím 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);

UseRequestLocalization inicializuje RequestLocalizationOptions objekt. Při každém požadavku je seznam v RequestLocalizationOptions vyčíslen a první zprostředkovatel, který může úspěšně určit kulturu požadavku, je použit. Výchozí zprostředkovatelé pocházejí z RequestLocalizationOptions třídy:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

Výchozí seznam jde od nejkonkrétnějšího k nejméně konkrétnímu. Později v článku uvidíme, jak můžete změnit pořadí a dokonce přidat poskytovatele vlastní kultury. Pokud žádný z poskytovatelů nemůže určit kulturní nastavení požadavku, použije se DefaultRequestCulture.

QueryStringRequestCultureProvider

Některé aplikace budou k nastavení CultureInfo používat řetězec dotazu. Pro aplikace, které používají přístup hlavičky cookie nebo Accept-Language, je přidání parametrů dotazu k URL adrese 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 řetězce dotazu culture a ui-culture. Následující příklad nastaví specifickou kulturu (jazyk a oblast) na španělštinu/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 kultury nastaví jak Culture, tak UICulture.

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

CookieRequestCultureProvider

Produkční aplikace často poskytují mechanismus pro nastavení kultury s kulturou ASP.NET Core cookie. Použijte metodu MakeCookieValue k vytvoření cookie.

Vrací CookieRequestCultureProviderDefaultCookieName výchozí cookie název používaný ke sledování preferovaných kulturních informací 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 Accept-Language v požadavku prohlížeče není neomylným způsobem, jak zjistit preferovaný 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 své kulturní nastavení.

Nastavte hlavičku HTTP pro rozhraní Accept-Language v IE

  1. Z ikony ozubeného kola klepněte na Internetové možnosti.

  2. Klepněte na Jazyky.

    Možnosti internetu

  3. Klepněte na Nastavit jazykové předvolby.

  4. Klepněte na Přidat jazyk.

  5. Přidejte jazyk.

  6. 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 program, 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ů kulturního prostředí žádosti o změnu

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 přehozeno, takže RequestLocalizationMiddleware hledá jazykové verze nejprve ze souborů cookie a potom z dotazového řetězce.

Jak jsme již zmínili, přidejte vlastního zprostředkovatele prostřednictvím AddInitialRequestCultureProvider, který nastaví pořadí na 0, takže tento zprostředkovatel má přednost před ostatními.

Nastavte kulturu programově

Tento ukázkový projekt Localization.StarterWeb na GitHubuCultureobsahuje 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>&copy; @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í kulturu 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);
}

Nelze připojit _SelectLanguagePartial.cshtml k ukázkovému kódu pro tento projekt. Projekt Localization.StarterWeb na GitHubu má kód pro předání RequestLocalizationOptions do Razor partial prostřednictvím kontejneru pro injektáž závislostí.

Vazba modelu pro data cesty a řetězce dotazů

Viz chování globalizace vazby modelu, dat směrování a řetězců 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 kód subkultury. 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í dvoupísmenného kódu jazykové verze ISO 639 přidruženého k jazyku a dvoupísmenného kódu subkultury ISO 3166 ve verzálkách 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).

Terms:

  • 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.
  • Kultura: Je to jazyk a volitelně i region.
  • Neutrální kultura: Kultura, která má zadaný jazyk, ale ne oblast. (například "en", "es")
  • Konkrétní kultura: Kultura, která má určený jazyk a region. (například "en-US", "en-GB", "es-CL")
  • Nadřazená kultura: Neutrální kultura, která obsahuje specifickou kulturu. (například "en" je nadřazenou verzí "en-US" a "en-GB")
  • Národní prostředí: Národní prostředí je stejné jako nastavení regionu.

Note

V desetinných polích možná nebudete moct zadávat desetinné čárky. Pokud chcete podporovat validaci jQuery pro neanglická národní prostředí, která používají čárku (",") jako desetinný oddělovač a jiné formáty dat než ve formátu angličtiny používané v USA, musíte provést kroky ke globalizaci aplikace. Pokyny k přidání desetinné čárky najdete v tomto komentáři GitHubu 4076 .

Note

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í jednoho LogLevel.Warning na každou žádost může vytvářet velké soubory protokolů s redundantními informacemi. Toto chování se v ASP.NET Core 3.0 změnilo. Zapíše RequestLocalizationMiddleware protokol typu LogLevel.Debug, který zmenšuje velikost produkčních protokolů.

Dodatečné zdroje

  • Last updated on