Poskytnutí lokalizovaných prostředků pro jazyky a jazykové verze v aplikaci ASP.NET Core

  • Článek

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

Jednou z úloh pro lokalizaci aplikace je poskytnutí lokalizovaných řetězců v souborech prostředků. Tento článek se zabývá prací se soubory prostředků.

SupportedCultures a SupportedUICultures

ASP.NET Core má dvě kolekce hodnot 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ší StringComparer.CurrentCulture informace o tom, jak server získá jazykovou verzi Určuje SupportedUICultures , které přeložené řetězce (ze souborů .resx ) vyhledá ResourceManager. Jednoduše ResourceManager vyhledá řetězce specifické pro jazykovou verzi, které jsou určeny CurrentUICulture. Každé vlákno v .NET má CurrentCulture a CurrentUICulture objekty. ASP.NET Core tyto hodnoty kontroluje při vykreslování funkcí závislých na jazykové verzi. Pokud je například jazyková verze aktuálního vlákna nastavená na "en-US" (angličtina, USA), DateTime.Now.ToLongDateString() zobrazí "Čtvrtek, 18. února 2016", ale pokud CurrentCulture je nastavena na "es-ES" (španělština, Španělsko), bude výstup "jueves, 18 de febrero de 2016".

Soubory prostředků

POZNÁMKA: Prohlížeč ResX a Editor poskytuje alternativní mechanismus pro práci se soubory prostředků pomocí editoru Visual Studio Code.

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 španělského prostředku 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 myši na složku, která bude obsahovat soubor prostředku, a pak vyberte 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 kódu jazyka a jazykové verze. 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 součástí názvu souboru (například en-us, fr-ca a en-gb). Tyto kódy 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).

Další kroky

Lokalizace aplikace zahrnuje také následující úlohy:

Další materiály

Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana a Hisham Bin Ateya

Jednou z úloh pro lokalizaci aplikace je poskytnutí lokalizovaných řetězců v souborech prostředků. Tento článek se zabývá prací se soubory prostředků.

SupportedCultures a SupportedUICultures

ASP.NET Core má dvě kolekce hodnot 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ší StringComparer.CurrentCulture informace o tom, jak server získá jazykovou verzi Určuje SupportedUICultures , které přeložené řetězce (ze souborů .resx ) vyhledá ResourceManager. Jednoduše ResourceManager vyhledá řetězce specifické pro jazykovou verzi, které jsou určeny CurrentUICulture. Každé vlákno v .NET má CurrentCulture a CurrentUICulture objekty. ASP.NET Core tyto hodnoty kontroluje při vykreslování funkcí závislých na jazykové verzi. Pokud je například jazyková verze aktuálního vlákna nastavená na "en-US" (angličtina, USA), DateTime.Now.ToLongDateString() zobrazí "Čtvrtek, 18. února 2016", ale pokud CurrentCulture je nastavena na "es-ES" (španělština, Španělsko), bude výstup "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 španělského prostředku 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 myši na složku, která bude obsahovat soubor prostředku, a pak vyberte 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 kódu jazyka a jazykové verze. 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 součástí názvu souboru (například en-us, fr-ca a en-gb). Tyto kódy 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).

Další kroky

Lokalizace aplikace zahrnuje také následující úlohy:

Další materiály