Sdílet prostřednictvím

Globalizace a lokalizace v ASP.NET Core

  • Článek

Poznámka:

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

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

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 v tomto článku ve verzi .NET 9.

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é přidávají nebo nahrazují pokyny v tomto článku, najdete v tématu ASP.NET globalizace a lokalizace jádraBlazor.

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:

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

Další materiály

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:

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

Další materiály

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. Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze, které podporujete
  3. 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í. IStringLocalizerResourceManager 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 SharedResourcepouze 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, 2016pokud 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:

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

    Vnořená kontextová nabídka: V Průzkumník řešení je pro prostředky otevřená místní nabídka. Druhá místní nabídka je otevřená pro přidání 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ů Uvítací španělština (es)

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 nastaví ResourcesPath hodnotu "Resources", takže relativní cesta k projektu pro home soubor francouzského zdroje kontroleru je Resources/Controllers.HomeController.fr.resx.ConfigureServices Případně můžete pomocí složek uspořádat soubory prostředků. home Pro 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ů 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
Prostředky/Controllers.HomeController.fr.resx Tečka
Prostředky/Controllers/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 AssemblyNamehodnoty , 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" v Index.fr.cshtml souboru.

  • AddDataAnnotationsLocalization přidává podporu lokalizovaných DataAnnotations ověřovacích zpráv prostřednictvím IStringLocalizer 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:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. 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

  1. Z ikony ozubeného kola klepněte na Možnosti internetu.

  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 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 souborů cookie nejprve a potom řetězec 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 Cultureobsahuje 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í 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ů.

Další materiály