Udostępnianie zlokalizowanych zasobów dla języków i kultur w aplikacji ASP.NET Core

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

Jednym z zadań lokalizowania aplikacji jest zapewnienie zlokalizowanych ciągów w plikach zasobów. Ten artykuł dotyczy pracy z plikami zasobów.

SupportedCultures i SupportedUICultures

ASP.NET Core ma dwie kolekcje wartości kultury i SupportedCulturesSupportedUICultures. Obiekt CultureInfo dla SupportedCultures określa wyniki funkcji zależnych od kultury, takich jak data, godzina, liczba i formatowanie waluty. SupportedCultures Określa również kolejność sortowania tekstu, konwencji wielkości liter i porównań ciągów. Zobacz StringComparer.CurrentCulture , aby uzyskać więcej informacji na temat sposobu pobierania kultury przez serwer. Funkcja SupportedUICultures określa, które przetłumaczone ciągi (z plików resx ) są sprawdzane przez element ResourceManager. Po ResourceManager prostu wyszukuje ciągi specyficzne dla kultury, które są określane przez CurrentUICulture. Każdy wątek na platformie .NET ma CurrentCulture obiekty i CurrentUICulture . ASP.NET Core sprawdza te wartości podczas renderowania funkcji zależnych od kultury. Jeśli na przykład kultura bieżącego wątku jest ustawiona na "en-US" (angielski, Stany Zjednoczone), DateTime.Now.ToLongDateString() wyświetla komunikat "thursday, 18 lutego 2016", ale jeśli CurrentCulture ustawiono wartość "es-ES" (hiszpański, Hiszpania), dane wyjściowe będą "jueves, 18 de febrero de 2016".

Pliki zasobów

UWAGA: Przeglądarka i edytor ResX udostępnia alternatywny mechanizm pracy z plikami zasobów przy użyciu programu Visual Studio Code.

Plik zasobu jest przydatnym mechanizmem oddzielania ciągów lokalizowalnych od kodu. Przetłumaczone ciągi dla języka innego niż domyślny są izolowane w plikach zasobów resx . Na przykład możesz utworzyć hiszpański plik zasobów o nazwie Welcome.es.resx zawierający przetłumaczone ciągi. "es" to kod języka hiszpańskiego. Aby utworzyć ten plik zasobów w programie Visual Studio:

1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy folder, który będzie zawierać plik zasobu, a następnie wybierz polecenie Dodaj>nowy element.

   

2. W polu Wyszukaj zainstalowane szablony wprowadź "zasób" i nadaj plikowi nazwę.

   

3. Wprowadź wartość klucza (ciąg natywny) w kolumnie Nazwa i przetłumaczony ciąg w kolumnie Wartość .

   

   Program Visual Studio wyświetla plik Welcome.es.resx .

   

Nazewnictwo plików zasobów

Zasoby są nazwane jako pełna nazwa typu ich klasy minus nazwa zestawu. Na przykład zasób francuski w projekcie, którego głównym zestawem jest LocalizationWebsite.Web.dll klasa LocalizationWebsite.Web.Startup , będzie mieć nazwę Startup.fr.resx. Zasób dla klasy LocalizationWebsite.Web.Controllers.HomeController będzie miał nazwę Kontrolery.HomeController.fr.resx. Jeśli przestrzeń nazw klasy docelowej nie jest taka sama jak nazwa zestawu, potrzebna będzie pełna nazwa typu. Na przykład w przykładowym projekcie zasób dla typu ExtraNamespace.Tools będzie miał nazwę ExtraNamespace.Tools.fr.resx.

W przykładowym projekcie ConfigureServices metoda ustawia ResourcesPath wartość "Resources", więc ścieżka względna projektu dla francuskiego pliku zasobu kontrolera domu to Resources/Controllers.HomeController.fr.resx. Alternatywnie można użyć folderów do organizowania plików zasobów. W przypadku kontrolera macierzystego ścieżka to Resources/Controllers/HomeController.fr.resx. Jeśli nie używasz ResourcesPath tej opcji, plik resx zostanie wyświetlony w katalogu podstawowym projektu. Plik zasobu dla elementu HomeController będzie miał nazwę Kontrolery.HomeController.fr.resx. Wybór konwencji nazewnictwa kropki lub ścieżki zależy od sposobu organizowania plików zasobów.

Nazwa zasobu	Nazewnictwo kropki lub ścieżki
Zasoby/kontrolery.HomeController.fr.resx	Dot
Resources/Controllers/HomeController.fr.resx	Ścieżka

Pliki zasobów używane @inject IViewLocalizer w Razor widokach są zgodne z podobnym wzorcem. Plik zasobu widoku może mieć nazwę przy użyciu nazewnictwa kropki lub nazewnictwa ścieżek. Razor wyświetl pliki zasobów naśladują ścieżkę skojarzonego pliku widoku. Zakładając, że ustawiliśmy ResourcesPath wartość "Resources", francuski plik zasobów skojarzony z widokiem może być jednym z Views/Home/About.cshtml następujących elementów:

• Resources/Views/Home/About.fr.resx

• Resources/Views.Home. About.fr.resx

Jeśli nie używasz ResourcesPath tej opcji, plik resx dla widoku będzie znajdować się w tym samym folderze co widok.

RootNamespaceAttribute

Atrybut RootNamespaceAttribute udostępnia przestrzeń nazw głównego zestawu, gdy główna przestrzeń nazw zestawu jest inna niż nazwa zestawu.

Ostrzeżenie

Taka sytuacja może wystąpić, gdy nazwa projektu nie jest prawidłowym identyfikatorem platformy .NET. Na przykład my-project-name.csproj użyje głównej przestrzeni nazw my_project_name i nazwy my-project-name zestawu prowadzącego do tego błędu.

Jeśli główna przestrzeń nazw zestawu różni się od nazwy zestawu:

• Lokalizacja nie działa domyślnie.
• Lokalizacja kończy się niepowodzeniem ze względu na sposób wyszukiwania zasobów w zestawie. RootNamespace to wartość czasu kompilacji, która nie jest dostępna dla procesu wykonywania.

Jeśli parametr RootNamespace różni się od AssemblyNameelementu , uwzględnij następujące wartości w AssemblyInfo.cs pliku (z wartościami parametrów zastąpionymi rzeczywistymi wartościami):

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

Powyższy kod umożliwia pomyślne rozwiązanie plików resx.

Zachowanie rezerwowe kultury

Podczas wyszukiwania zasobu lokalizacja angażuje się w "rezerwowanie kultury". Począwszy od żądanej kultury, jeśli nie zostanie znaleziona, przywraca kulturę nadrzędną tej kultury. Na bok CultureInfo.Parent właściwość reprezentuje kulturę nadrzędną. Zwykle (ale nie zawsze) oznacza usunięcie znaku narodowego z kodu językowego i kulturowego. Na przykład dialekt hiszpański mówiony w Meksyku to "es-MX". Ma element nadrzędny "es" — hiszpański, nieokreślony dla dowolnego kraju.

Załóżmy, że witryna otrzymuje żądanie zasobu "Powitanie" przy użyciu kultury "fr-CA". System lokalizacji wyszukuje następujące zasoby w kolejności i wybiera pierwsze dopasowanie:

• Welcome.fr-CA.resx
• Witamy.fr.resx
• Welcome.resx (jeśli NeutralResourcesLanguage jest to "fr-CA")

Jeśli na przykład usuniesz projektant kultury ".fr" i masz ustawioną kulturę na język francuski, domyślny plik zasobu jest odczytywany, a ciągi są zlokalizowane. Usługa Resource Manager wyznacza domyślny lub rezerwowy zasób, jeśli nic nie spełnia żądanej kultury. Jeśli chcesz po prostu zwrócić klucz, gdy brakuje zasobu dla żądanej kultury, nie musisz mieć domyślnego pliku zasobu.

Generowanie plików zasobów za pomocą programu Visual Studio

Jeśli utworzysz plik zasobu w programie Visual Studio bez kultury w nazwie pliku (na przykład Welcome.resx), program Visual Studio utworzy klasę języka C# z właściwością dla każdego ciągu. Zwykle nie jest to to, czego potrzebujesz z ASP.NET Core. Zazwyczaj nie masz domyślnego pliku zasobu resx (pliku resx bez nazwy kultury). Zalecamy utworzenie pliku resx o nazwie kultury (na przykład Welcome.fr.resx). Podczas tworzenia pliku resx o nazwie kultury program Visual Studio nie wygeneruje pliku klasy.

Dodawanie innych kultur

Każda kombinacja języka i kultury (inna niż język domyślny) wymaga unikatowego pliku zasobu. Pliki zasobów można tworzyć dla różnych kultur i ustawień regionalnych, tworząc nowe pliki zasobów, w których kody językowe są częścią nazwy pliku (na przykład en-us, fr-ca i en-gb). Te kody są umieszczane między nazwą pliku a rozszerzeniem pliku resx , jak w pliku Welcome.es-MX.resx (hiszpański/meksyk).

Następne kroki

Lokalizowanie aplikacji obejmuje również następujące zadania:

• Umożliwia zlokalizowanie zawartości aplikacji.
• Implementowanie strategii wybierania języka/kultury dla każdego żądania

Dodatkowe zasoby

• Dostawca kultury adresu URL korzystający z oprogramowania pośredniczącego jako filtry w programie ASP.NET Core
• Globalne stosowanie elementu RouteDataRequest CultureProvider z oprogramowaniem pośredniczącym jako filtrami
• Globalizacja i lokalizacja w ASP.NET Core
• Lokalizacja zawartości aplikacji ASP.NET Core
• Strategie wybierania języka i kultury w zlokalizowanej aplikacji ASP.NET Core
• Rozwiązywanie problemów z lokalizacją podstawową ASP.NET
• Globalizowanie i lokalizowanie aplikacji platformy .NET
• Localization.StarterWeb projektu użytego w artykule.
• Zasoby w plikach resx
• Microsoft Multilingual App Toolkit
• Lokalizacja i typy ogólne