Lokalizowanie ciągów w interfejsie użytkownika i manifeście pakietu aplikacji

Aby uzyskać więcej informacji o propozycji wartości z lokalizacji swojej aplikacji Windows App SDK, zobacz Globalizacja i lokalizacja.

Jeśli chcesz, aby aplikacja obsługiwała różne języki wyświetlania i masz ciągi tekstowe w swoim kodzie, znaczniku XAML lub manifeście pakietu aplikacji, przenieś te ciągi do pliku zasobów (.resw). Następnie możesz utworzyć przetłumaczoną kopię tego pliku zasobów dla każdego języka obsługiwanego przez aplikację.

Literały ciągów zakodowanych na stałe mogą pojawiać się w kodzie imperatywnym lub w znacznikach XAML, na przykład jako właściwość Text obiektu TextBlock. Mogą one również być wyświetlane w pliku źródłowym manifestu pakietu aplikacji (pliku Package.appxmanifest), na przykład jako wartość pola Display name na karcie Application projektanta manifestu programu Visual Studio. Przenieś te ciągi do pliku zasobów (resw) i zastąp zakodowane na stałe literały ciągu w aplikacji i w manifeście odwołaniami do identyfikatorów zasobów.

W przeciwieństwie do zasobów graficznych, gdzie w pliku zasobu znajduje się tylko jeden element graficzny, wiele zasobów tekstowych znajduje się w pliku zasobu tekstowego. Plik zasobów stringów to plik zasobów typu .resw, który zazwyczaj tworzysz w katalogu \Strings w swoim projekcie. Aby dowiedzieć się, jak używać kwalifikatorów w nazwach plików zasobów (.resw), zobacz sekcję Dostosowywanie zasobów pod kątem języka, skalowania i innych kwalifikatorów.

Przechowywanie ciągów w pliku zasobów

1. Ustaw domyślny język aplikacji.

   1. Po otwarciu rozwiązania w programie Visual Studio otwórz Package.appxmanifest.
   2. Na karcie Aplikacja upewnij się, że język domyślny jest odpowiednio ustawiony (na przykład "en" lub "en-US"). W pozostałych krokach przyjęto założenie, że dla języka domyślnego ustawiono wartość "en-US".

   Uwaga / Notatka

   Co najmniej należy podać zasoby ciągów zlokalizowane dla tego języka domyślnego. Są to zasoby, które zostaną załadowane, jeśli nie można znaleźć lepszego dopasowania dla preferowanego języka użytkownika lub ustawień języka wyświetlania.

2. Utwórz plik zasobów (resw) dla języka domyślnego.

   1. W węźle projektu utwórz nowy folder i nadaj mu nazwę Strings.
   2. W obszarze Stringsutwórz nowy podfolder i nadaj mu nazwę en-US.
   3. W obszarze en-USutwórz nowy plik zasobów (resw) (w obszarze typów plików WinUI w oknie dialogowym Dodawanie nowego elementu) i upewnij się, że ma on nazwę Resources.resw.

   Uwaga / Notatka

   Jeśli masz pliki zasobów platformy .NET (resx), które chcesz portować, zobacz Przenoszenie kodu XAML i interfejsu użytkownika.

3. Otwórz Resources.resw i dodaj te zasoby tekstowe.

   Strings/en-US/Resources.resw

   

   W tym przykładzie "Greeting" to identyfikator zasobu tekstowego, do którego można odwoływać się w znacznikach, jak pokażemy. Dla identyfikatora "Greeting" jest przypisany ciąg do właściwości Text, a także jest przypisany ciąg do właściwości Width. "Greeting.Text" to przykład identyfikatora właściwości, ponieważ odpowiada właściwości elementu interfejsu użytkownika. Możesz również dodać "Greeting.Foreground" w kolumnie Nazwa i ustawić wartość na "Czerwony". Identyfikator "Pożegnanie" jest prostym identyfikatorem zasobu tekstowego; nie ma właściwości podrzędnych i można go załadować z kodu imperatywnego, jak pokażemy. Kolumna Komentarz jest dobrym miejscem, aby podać wszelkie specjalne instrukcje dla tłumaczy.

   W tym przykładzie, ponieważ mamy prosty wpis identyfikatora zasobu ciągu o nazwie "Pożegnanie", nie możemy również mieć identyfikatorów właściwości na podstawie tego samego identyfikatora. Dlatego dodanie elementu "Farewell.Text" spowodowałoby błąd zduplikowanego wpisu podczas kompilowania Resources.resw.

   Identyfikatory zasobów są bez uwzględniania wielkości liter i muszą być unikatowe dla pliku zasobu. Pamiętaj, aby użyć znaczących identyfikatorów zasobów w celu zapewnienia dodatkowego kontekstu dla tłumaczy. Nie zmieniaj identyfikatorów zasobów po wysłaniu zasobów tekstowych do tłumaczenia. Zespoły lokalizacyjne używają identyfikatora zasobu do śledzenia dodatków, usuwania i aktualizacji w zasobach. Zmiany identyfikatorów zasobów — nazywane również "przesunięciem identyfikatorów zasobów" — wymagają przetłumaczenie ciągów, ponieważ będą wyświetlane tak, jakby ciągi zostały usunięte, a inne zostały dodane.

Zapoznaj się z identyfikatorem zasobu ciągu z języka XAML

Aby skojarzyć kontrolkę lub inny element w znaczniku z identyfikatorem zasobu ciągu, należy użyć dyrektywy x:Uid.

<TextBlock x:Uid="Greeting"/>

W czasie wykonywania \Strings\en-US\Resources.resw jest załadowany (ponieważ obecnie jest to jedyny plik zasobów w projekcie). Dyrektywa x:Uid w TextBlock powoduje wyszukiwanie identyfikatorów właściwości w Resources.resw zawierających ciąg identyfikatora zasobu "Greeting". Znaleziono identyfikatory właściwości "Greeting.Text" i "Greeting.Width", a ich wartości są przypisywane do TextBlock, przesłaniając wartości ustawione lokalnie w znaczniku. Wartość "Greeting.Foreground" byłaby również zastosowana, gdybyś ją dodał. Jednak tylko identyfikatory właściwości są używane do ustawiania właściwości na elementach znaczników XAML, więc ustawienie x:Uid na "Pożegnanie" na tym TextBlock nie miałoby wpływu. Resources.resw zawiera identyfikator zasobu ciągu "Pożegnanie", ale nie zawiera żadnych identyfikatorów właściwości.

Podczas przypisywania identyfikatora zasobu ciągu do elementu XAML upewnij się, że wszystkie identyfikatory właściwości dla tego identyfikatora są odpowiednie dla elementu XAML. Na przykład, jeśli ustawisz x:Uid="Greeting" na TextBlock, wartość "Greeting.Text" zostanie rozpoznana, ponieważ typ TextBlock posiada właściwość Text. Jeśli jednak ustawisz x:Uid="Greeting" na przycisku , to "Greeting.Text" spowoduje błąd czasu wykonywania, ponieważ typ przycisku nie ma właściwości Text. Jednym z rozwiązań w tym przypadku jest utworzenie identyfikatora właściwości o nazwie "ButtonGreeting.Content" i ustawienie x:Uid="ButtonGreeting" na Button.

Zamiast ustawiać szerokość z pliku zasobów, prawdopodobnie chcesz zezwolić kontrolkom na dynamiczne dopasowanie rozmiaru do zawartości.

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Odwołaj się do identyfikatora zasobu tekstowego w kodzie

Zasób ciągu można jawnie załadować na podstawie prostego identyfikatora zasobu ciągu.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Możesz użyć tego samego kodu z poziomu projektu Biblioteka klas. W czasie wykonywania są ładowane zasoby aplikacji hostujące bibliotekę. Zalecamy, aby biblioteka ładuje zasoby z aplikacji, która ją hostuje, ponieważ aplikacja prawdopodobnie będzie miała większy stopień lokalizacji. Jeśli biblioteka musi dostarczyć zasoby, powinna ona nadać aplikacji hostingowej opcję zastąpienia tych zasobów jako danych wejściowych.

Jeśli nazwa zasobu jest segmentowana (zawiera znaki "."), zastąp kropki znakami ukośnika ("/") w nazwie zasobu. Identyfikatory właściwości, przykładowo, zawierają kropki; dlatego trzeba dokonać tego zastąpienia, aby załadować jeden z tych elementów z kodu.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

Jeśli masz wątpliwości, możesz użyć MakePri.exe, aby zrzucić plik PRI aplikacji. Każdy zasób uri jest wyświetlany w wyeksportowanym pliku.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Odwołaj się do identyfikatora zasobu ciągu tekstowego z manifestu pakietu aplikacji.

1. Otwórz plik źródłowy manifestu pakietu Twojej aplikacji (plik Package.appxmanifest), w którym domyślnie Display name Twojej aplikacji jest wyrażany jako literał ciągu.

   

2. Aby utworzyć zlokalizowaną wersję tego ciągu, otwórz Resources.resw i wprowadź nowy zasób ciągu o nazwie "AppDisplayName" i wartości "Adventure Works Cycles".

3. Zastąp literał ciągu nazwy wyświetlanej odwołaniem do właśnie utworzonego identyfikatora zasobu ciągu ("AppDisplayName"). W tym celu użyjesz schematu identyfikatora URI ms-resource (uniform Resource Identifier).

   

4. Powtórz ten proces dla każdego ciągu w manifeście, który chcesz zlokalizować. Na przykład krótka nazwa aplikacji (którą można skonfigurować do wyświetlania na kafelku aplikacji w menu Start). Aby uzyskać listę wszystkich elementów w manifeście pakietu aplikacji, które można lokalizować, zobacz Lokalizowalne elementy manifestu.

Lokalizowanie zasobów ciągów

1. Utwórz kopię pliku zasobów (resw) dla innego języka.

   1. W obszarze "Ciągi" utwórz nowy podfolder i nadaj mu nazwę "de-DE" dla Deutsch (Deutschland).

   Uwaga / Notatka

   Dla nazwy folderu można użyć dowolnego tagu języka BCP-47 . Zobacz , jak dostosować zasoby pod kątem języka, skalowania i innych kwalifikatorów, oraz, aby uzyskać szczegółowe informacje na temat kwalifikatora języka i listy typowych tagów języka. 2. Utwórz kopię Strings/en-US/Resources.resw w folderze Strings/de-DE.

2. Przetłumacz ciągi.

   1. Otwórz Strings/de-DE/Resources.resw i przetłumacz wartości w kolumnie Wartość. Nie musisz tłumaczyć komentarzy.

   Strings/de-DE/Resources.resw

   

Jeśli chcesz, możesz powtórzyć kroki 1 i 2 dla kolejnego języka.

Strings/fr-FR/Resources.resw

Przetestuj aplikację

Przetestuj aplikację pod kątem domyślnego języka wyświetlania. Następnie możesz zmienić język wyświetlania w obszarze Ustawienia>Czas i język>Region i język>Języki i ponownie przetestować aplikację. Spójrz na ciągi w interfejsie użytkownika oraz w powłoce, takie jak pasek tytułowy (czyli nazwa wyświetlana) i krótka nazwa na kafelkach.

Uwzględnianie ciągów w wielu plikach zasobów

Możesz zachować wszystkie ciągi w jednym pliku zasobów (resw) lub można je uwzględnić w wielu plikach zasobów. Na przykład możesz zachować komunikaty o błędach w jednym pliku zasobów, ciągach manifestu pakietu aplikacji w innym i ciągach interfejsu użytkownika w jednej trzeciej. W takim przypadku struktura folderów będzie wyglądać następująco.

Aby skonkretyzować odwołanie identyfikatora zasobu ciągu znaków do określonego pliku, wystarczy dodać /<resources-file-name>/ przed identyfikatorem. W poniższym przykładzie znaczników przyjęto założenie, że ErrorMessages.resw zawiera zasób o nazwie "PasswordTooWeak.Text" i którego wartość opisuje błąd.

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Musisz tylko dodać /<resources-file-name>/ przed identyfikatorem zasobu ciągu w plikach Resources Files innych niżResources.resw. Dzieje się tak dlatego, że "Resources.resw" jest domyślną nazwą pliku, więc uznawana jest, jeśli pominie się nazwę pliku (tak jak w poprzednich przykładach w tym temacie).

W poniższym przykładzie kodu przyjęto założenie, że ErrorMessages.resw zawiera zasób, którego nazwa to "NiezgodneHasła" i którego wartość opisuje błąd.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Jeśli chcesz przenieść zasób "AppDisplayName" z Resources.resw i do ManifestResources.resw, w manifeście pakietu aplikacji zmienisz ms-resource:AppDisplayName na ms-resource:/ManifestResources/AppDisplayName.

Jeśli nazwa pliku zasobu jest segmentowana (zawiera znaki "."), pozostaw kropki w nazwie, gdy się do niej odwołujesz. Nie zastępować kropek ukośnikami ("/"), tak jak w przypadku nazwy zasobu.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("Err.Msgs");

Jeśli masz wątpliwości, możesz użyć MakePri.exe, aby zrzucić plik PRI aplikacji. Każdy zasób uri jest wyświetlany w wyeksportowanym pliku.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Załaduj ciąg dla określonego języka lub innego kontekstu

Domyślny ResourceContext (uzyskany podczas tworzenia ResourceLoader) zawiera wartość kwalifikatora dla każdej nazwy kwalifikatora reprezentującego domyślny kontekst środowiska uruchomieniowego (innymi słowy ustawienia dla bieżącego użytkownika i maszyny). Pliki zasobów (.resw) są dopasowywane — na podstawie kwalifikatorów w nazwach — do wartości kwalifikatorów w danym kontekście środowiska uruchomieniowego.

Czasami jednak aplikacja ma przesłonić ustawienia systemowe i jawnie określać język, skalę lub inną wartość kwalifikatora do użycia podczas wyszukiwania pasującego pliku zasobów do załadowania. Możesz na przykład chcieć, aby użytkownicy mogli wybrać alternatywny język etykietek narzędzi lub komunikatów o błędach.

Można to osiągnąć poprzez utworzenie nowego ResourceContext, nadpisując jego wartości, a następnie korzystając z tego obiektu kontekstu w wyszukiwaniach ciągów.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

Użycie QualifierValues jak w powyższym przykładzie kodu działa dla dowolnego kwalifikatora. W szczególnym przypadku języka możesz zamiast tego zrobić to.

resourceContext.Languages = new string[] { "de-DE" };

Ładowanie ciągów z biblioteki klas

Zasoby ciągów referencyjnej biblioteki klas są zwykle dodawane do podfolderu w pakiecie, w którym są uwzględniane podczas procesu kompilacji. Identyfikator zasobu takiego ciągu zwykle przyjmuje formę LibraryName/ResourcesFileName/ResourceIdentifier.

Biblioteka może uzyskać ResourceLoader dla swoich zasobów. Na przykład poniższy kod ilustruje, w jaki sposób biblioteka lub aplikacja, która odwołuje się do niej, może uzyskać ResourceLoader dla zasobów ciągów biblioteki.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

Jeśli masz wątpliwości co do ścieżki, możesz użyć opcji wiersza polecenia MakePri.exe, aby wygenerować plik PRI swojego składnika lub biblioteki. Każdy zasób uri jest wyświetlany w wyeksportowanym pliku.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Ładowanie ciągów z innych pakietów

Zasoby pakietu aplikacji są zarządzane i uzyskiwane za pośrednictwem własnej mapy zasobów najwyższego poziomu (ResourceMap), która jest dostępna z poziomu menedżera zasobów (ResourceManager). W każdym pakiecie różne składniki mogą mieć własne ResourceMap poddrzewa, do których można uzyskać dostęp za pośrednictwem ResourceMap.GetSubtree.

Pakiet framework może uzyskać dostęp do własnych zasobów przy użyciu bezwzględnego identyfikatora URI zasobów. Aby uzyskać więcej informacji, zobacz również schematów identyfikatorów URI w dokumentacji platformy UWP.

Ładowanie ciągów znaków w aplikacjach rozpakowanych

Od wersji 1903 systemu Windows (aktualizacja z maja 2019 r.), aplikacje rozpakowane mogą również korzystać z systemu zarządzania zasobami.

Wystarczy utworzyć kontrolki/biblioteki zestawu SDK aplikacji systemu Windows i przechowywać wszystkie ciągi w pliku zasobów. Następnie można odwołać się do identyfikatora zasobu ciągu zXAML, odwołać się do identyfikatora zasobu ciągu zkodu lub ładować ciągi z biblioteki klas.

Aby użyć zasobów w aplikacjach rozpakowanych, należy wykonać kilka czynności:

1. Użyj przeciążonego konstruktora ResourceManager, aby przekazać nazwę pliku .pri swojej aplikacji podczas rozpoznawania zasobów z kodu, ponieważ w sytuacjach, gdy aplikacja nie jest opakowana, nie ma widoku domyślnego.
2. Użyj MakePri.exe, aby ręcznie wygenerować plik resources.pri aplikacji.
   • Uruchom makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri
   • <PRICONFIG> musi pominąć sekcję "<packaging>", aby wszystkie zasoby zostały połączone w jednym pliku resources.pri. Jeśli używasz domyślnego pliku konfiguracji MakePri.exe utworzonego przez createconfig, należy usunąć sekcję "<pakowania>" ręcznie po jej utworzeniu.
   • <PRICONFIG> musi zawierać wszystkie właściwe indeksatory wymagane, aby połączyć wszystkie zasoby w projekcie w jeden plik resources.pri. Domyślny plik konfiguracji MakePri.exe utworzony przez createconfig zawiera wszystkie indeksatory.
   • Jeśli nie używasz domyślnej konfiguracji, upewnij się, że indeksator PRI jest włączony (przejrzyj domyślną konfigurację, aby dowiedzieć się, jak to zrobić) w celu scalenia PRI znalezionych w odwołaniach projektowych, odwołaniach NuGet i innych, umieszczonych w katalogu głównym projektu.

     Uwaga / Notatka

     Pominięcie /IndexNameoraz brak manifestu aplikacji w projekcie powodują, że przestrzeń nazw IndexName/root pliku PRI jest automatycznie ustawiana na Application, co środowisko uruchomieniowe rozpoznaje w przypadku aplikacji rozpakowanych (usuwa to wcześniejszą silną zależność od identyfikatora pakietu). Podczas określania identyfikatorów URI zasobów, jeśli pominiesz główną przestrzeń nazw, odwołanie ms-resource:/// zinterpretuje to jako Application jako główną przestrzeń nazw dla aplikacji rozpakowanych (lub możesz jawnie określić Application, jak w ms-resource://Application/).

3. Skopiuj plik PRI do katalogu wyjściowego kompilacji .exe
4. Uruchamianie .exe

   Uwaga / Notatka

   System zarządzania zasobami używa języka wyświetlania systemu, a nie listy preferowanych języków użytkownika podczas rozpoznawania zasobów na podstawie języka w aplikacjach rozpakowanych. Lista preferowanych języków użytkownika jest używana tylko dla spakowanych aplikacji zestawu SDK aplikacji systemu Windows.

Ważne interfejsy API

• ApplicationModel.Resources.ResourceLoader

Zobacz także

• Przykład MRT Core
• Jak załadować zasoby ciągów