Lokalizace řetězců v uživatelském rozhraní a manifestu balíčku aplikace

Další informace o hodnotové nabídce lokalizace aplikace Windows App SDK najdete v tématu Globalizace a lokalizace.

Pokud chcete, aby vaše aplikace podporovala různé jazyky zobrazení a máte řetězcové literály v kódu, kódu XAML nebo v manifestu balíčku aplikace, přesuňte tyto řetězce do souboru prostředků (.resw). Pak můžete vytvořit přeloženou kopii tohoto souboru prostředků pro každý jazyk, který vaše aplikace podporuje.

Pevně zakódované řetězcové literály se mohou objevit v imperativním kódu nebo v kódu XAML, například jako vlastnost Text v TextBlock. Mohou se také objevit ve zdrojovém souboru manifestu balíčku aplikace (soubor Package.appxmanifest), například jako hodnota pro Zobrazovaný název na kartě Aplikace v Návrháři manifestu Visual Studio. Přesuňte tyto řetězce do souboru prostředků (.resw) a místo pevně zapsaných řetězcových literálů ve vaší aplikaci a manifestu použijte odkazy na identifikátory prostředků.

Na rozdíl od prostředků image, kde je v souboru prostředků image obsažen pouze jeden prostředek image, více prostředků řetězce jsou obsaženy v řetězcovém souboru prostředků. Soubor prostředků řetězce je Resources File (.resw) a obvykle tento typ prostředku vytvoříte ve složce \Strings ve vašem projektu. Základní informace o použití kvalifikátorů v názvech souborů prostředků (.resw) najdete v tématu Přizpůsobení prostředků pro jazyk, škálování a další kvalifikátory.

Uložte řetězce do souboru prostředků

1. Nastavte výchozí jazyk aplikace.

   1. Otevřete Package.appxmanifestv sadě Visual Studio, když máte otevřené řešení.
   2. Na kartě Aplikace ověřte, že je správně nastaven výchozí jazyk (například "en" nebo "en-US"). Zbývající kroky předpokládají, že jste nastavili výchozí jazyk na "en-US".

   Poznámka:

   Minimálně je potřeba zadat zdroje řetězců lokalizované pro tento výchozí jazyk. Jedná se o zdroje, které se načtou, pokud nelze nalézt lepší shodu pro preferovaný jazyk uživatele nebo nastavení jeho jazyka zobrazení.

2. Vytvořte soubor prostředků (.resw) pro výchozí jazyk.

   1. Pod uzlem projektu vytvořte novou složku a pojmenujte ji Strings.
   2. V části Stringsvytvořte novou podsložku a pojmenujte ji en-US.
   3. V části en-USvytvořte nový soubor prostředků (.resw) (pod winUI typy souborů v dialogovém okně Přidat novou položku) a ověřte, že má název Resources.resw.

   Poznámka:

   Pokud máte soubory prostředků .NET (.resx), které chcete portovat, viz Portování XAML a uživatelského rozhraní.

3. Otevřete Resources.resw a přidejte tyto řetězcové zdroje.

   Strings/en-US/Resources.resw

   

   V tomto příkladu je "Greeting" identifikátor prostředku řetězce, na který můžete odkazovat z kódu, jak si ukážeme. Pro identifikátor "Greeting" je řetězec k dispozici pro vlastnost Text a řetězec k dispozici pro vlastnost Width. "Greeting.Text" je příkladem identifikátoru vlastnosti, protože odpovídá vlastnosti prvku uživatelského rozhraní. Můžete také přidat "Greeting.Foreground" ve sloupci Název a nastavit jeho hodnotu na "Červená". Identifikátor "Farewell" je jednoduchý řetězcový identifikátor prostředku; nemá žádné dílčí vlastnosti a dá se načíst z imperativního kódu, jak si ukážeme dále. Sloupec Komentář je dobrým místem pro poskytnutí jakýchkoli zvláštních pokynů překladatelům.

   V tomto příkladu, protože máme jednoduchou položku identifikátoru řetězce s názvem "Farewell", nemůžeme také mít identifikátory vlastností založené na tomto identifikátoru. Přidání "Farewell.Text" by tedy při sestavování Resources.reswzpůsobovalo chybu duplicitní položky .

   Identifikátory prostředků nerozlišují malá a velká písmena a musí být jedinečné pro každý soubor prostředků. Nezapomeňte použít smysluplné identifikátory prostředků k poskytnutí dalšího kontextu pro překladatele. Neměňte identifikátory prostředků poté, co byly řetězcové prostředky odeslány k překladu. Lokalizační týmy používají identifikátor prostředku ke sledování přidávání, odstraňování a aktualizací v prostředcích. Změny identifikátorů prostředků, které se také označují jako posun identifikátorů prostředků, vyžadují překládání řetězců, protože se zobrazí, jako kdyby byly řetězce odstraněny a další přidané.

Odkaz na identifikátor prostředku řetězce z XAML

Pomocí direktivy x:Uid přidružíte ovládací nebo jiný prvek ve vašem označení k identifikátoru řetězcového prostředku.

<TextBlock x:Uid="Greeting"/>

Při spuštění je načten \Strings\en-US\Resources.resw (protože právě teď je to jediný soubor zdrojů v projektu). Direktiva x:Uid na TextBlock způsobí provedení vyhledávání pro nalezení identifikátorů vlastností uvnitř Resources.resw, které obsahují identifikátor řetězce prostředku "Greeting". Jsou nalezeny identifikátory vlastností "Greeting.Text" a "Greeting.Width" a jejich hodnoty se použijí na TextBlock , čímž přepisují všechny hodnoty nastavené místně ve značkovacím jazyce. Pokud byste tuto hodnotu přidali, byla by použita také hodnota Greeting.Foreground. K nastavení vlastností u elementů značek XAML se ale používají pouze identifikátory vlastností, takže nastavení x:Uid na "Farewell" na tomto Objektu TextBlock by nemělo žádný vliv. Resources.resw obsahuje identifikátor prostředku řetězce "Farewell", ale neobsahuje pro něj žádné identifikátory vlastností.

Při přiřazování identifikátoru řetězce prostředku elementu XAML se ujistěte, že všechny identifikátory vlastností pro tento identifikátor jsou vhodné pro element XAML. Pokud například nastavíte x:Uid="Greeting" na TextBlock, pak se "Greeting.Text" vyhodnotí, protože typ TextBlock má vlastnost Text. Pokud ale nastavíte x:Uid="Greeting"tlačítko, způsobí "Greeting.Text" chybu za běhu, protože typ tlačítka nemá vlastnost Text. Jedním z řešení pro tento případ je vytvoření identifikátoru vlastnosti s názvem ButtonGreeting.Content a nastaveným x:Uid="ButtonGreeting" na tlačítko.

Místo toho, abyste nastavovali šířku z v souboru prostředků, pravděpodobně budete chtít povolit, aby se ovládací prvky dynamicky přizpůsobovaly obsahu.

Poznámka:

Pro připojených vlastnostípotřebujete speciální syntaxi ve sloupci Název souboru .resw. Pokud například chcete nastavit hodnotu pro připojenou vlastnost AutomationProperties.Name pro identifikátor "Greeting", zadali byste to do sloupce Název.

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

Odkazování na řetězcový identifikátor prostředku z kódu

Prostředek řetězce můžete explicitně načíst na základě jednoduchého identifikátoru řetězce.

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

Stejný kód můžete použít v rámci projektu knihovny tříd. Za běhu se načítají prostředky aplikace, která je hostitelem knihovny. Doporučujeme, aby knihovna načítá prostředky z aplikace, která ji hostuje, protože aplikace pravděpodobně bude mít větší stupeň lokalizace. Pokud knihovna potřebuje poskytnout prostředky, měla by dát hostitelské aplikaci možnost nahradit tyto prostředky jako vstup.

Pokud je název prostředku segmentovaný (obsahuje "."), nahraďte tečky lomítkem ("/") v názvu. Identifikátory vlastností, například obsahují tečky; Proto byste tuto náhradu museli provést, abyste mohli načíst některý z nich z kódu.

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

Pokud máte pochybnosti, můžete k vypsání souboru PRI aplikace použít MakePri.exe. V souboru s výpisem se zobrazí uri jednotlivých prostředků.

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

Odkaz na identifikátor řetězce z manifestu balíčku aplikace

1. Otevřete zdrojový soubor manifestu Package.appxmanifest balíčku aplikace (soubor), ve kterém se ve výchozím nastavení Display name aplikace vyjadřuje jako řetězcový literál.

   

2. Pokud chcete vytvořit lokalizovatelnou verzi tohoto řetězce, otevřete Resources.resw a přidejte nový řetězcový prostředek s názvem "AppDisplayName" a hodnotou "Adventure Works Cycles".

3. Nahraďte řetězcový literál názvu zobrazení odkazem na identifikátor prostředku řetězce, který jste právě vytvořili ("AppDisplayName"). K tomu použijete schéma identifikátoru ms-resource URI (Uniform Resource Identifier).

   

4. Tento postup opakujte pro každý řetězec v manifestu, který chcete lokalizovat. Například krátký název vaší aplikace (který můžete nakonfigurovat tak, aby se zobrazoval na dlaždici vaší aplikace na obrazovce Start). Pro seznam všech položek v manifestu balíčku aplikace, které můžete lokalizovat, viz lokalizovatelné položky manifestu.

Lokalizace řetězcových prostředků

1. Vytvořte kopii souboru prostředků (.resw) pro použití v jiném jazyce.

   1. V části "Strings" vytvořte novou podsložku a pojmenujte ji "de-DE" pro Deutsch (Deutschland).

   Poznámka:

   Pro název složky můžete použít libovolnou jazykovou značku BCP-47. Podrobnosti o kvalifikátoru jazyka a seznamu běžných jazykových značek najdete v tématu Přizpůsobení prostředků pro jazyk, škálování a další kvalifikátory . 2. Vytvořte kopii Strings/en-US/Resources.resw ve Strings/de-DE složce.

2. Přeložte řetězce.

   1. Otevřete Strings/de-DE/Resources.resw a přeložte hodnoty ve sloupci Hodnota. Komentáře nemusíte překládat.

   Strings/de-DE/Resources.resw

   

Pokud chcete, můžete kroky 1 a 2 zopakovat pro další jazyk.

Strings/fr-FR/Resources.resw

Testování aplikace

Otestujte aplikaci pro výchozí jazyk zobrazení. Potom můžete změnit jazyk zobrazení v Nastavení>Čas a jazyk>Oblast a jazyk>Jazyky a svou aplikaci znovu otestovat. Podívejte se na řetězce ve svém uživatelském rozhraní a také v shell prostředí (například na panel s titulkem, což je vaše zobrazované jméno, a na krátký název na vašich dlaždicích).

Poznámka:

Pokud se dá najít název složky, který odpovídá nastavení jazyka zobrazení, pak se načte soubor Resources uvnitř této složky. V opačném případě dojde k použití náhradního řešení, které skončí u prostředků výchozího jazyka vaší aplikace.

Rozdělování řetězců do více souborů prostředků

Všechny své řetězce můžete ponechat v jednom souboru prostředků (soubor .resw) nebo je můžete rozdělit mezi více souborů prostředků. Můžete například chtít zachovat chybové zprávy v jednom souboru zdrojů, řetězce balíčku manifestu aplikace v jiném souboru a řetězce uživatelského rozhraní ve třetím. V takovém případě by struktura složek vypadala takto.

Chcete-li omezit odkaz na identifikátor řetězcového prostředku na konkrétní soubor, stačí přidat /<resources-file-name>/ před identifikátor. Následující příklad značení předpokládá, že ErrorMessages.resw obsahuje prostředek, jehož název je "PasswordTooWeak.Text" a jehož hodnota popisuje chybu.

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

Je třeba přidat /<resources-file-name>/ před identifikátor řetězce pro soubory prostředků jiné nežaResources.resw. Důvodem je to, že "Resources.resw" je výchozí název souboru, takže se předpokládá, že pokud vynecháte název souboru (jak jsme to udělali v předchozích příkladech v tomto tématu).

Následující příklad kódu předpokládá, že obsahuje prostředek, ErrorMessages.resw jehož název je "MismatchedPasswords" a jehož hodnota popisuje chybu.

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

Pokud byste chtěli přesunout prostředek "AppDisplayName" z Resources.resw a do ManifestResources.resw, pak v manifestu balíčku aplikace byste změnili ms-resource:AppDisplayName na ms-resource:/ManifestResources/AppDisplayName.

Pokud je název souboru prostředku rozdělený (obsahuje znaky "."), ponechte v názvu tečky, když na něj odkazujete. Nepoužívejte místo teček znaky lomítka ("/"), jako byste to dělali pro název prostředku.

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

Pokud máte pochybnosti, můžete k vypsání souboru PRI aplikace použít MakePri.exe. V souboru s výpisem se zobrazí uri jednotlivých prostředků.

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

Načti řetězec pro konkrétní jazyk nebo jiný kontext

Výchozí ResourceContext (který je získán při vytváření ResourceLoader) obsahuje hodnotu kvalifikátoru pro každý název kvalifikátoru, který představuje výchozí kontext prostředí runtime (jinými slovy, nastavení pro aktuálního uživatele a počítač). Soubory prostředků (.resw) jsou porovnávány—na základě kvalifikátorů v jejich názvech—s hodnotami kvalifikátorů v daném kontextu běhového prostředí.

Někdy ale můžete chtít, aby vaše aplikace přepsala systémová nastavení a přesně uvedla jazyk, měřítko nebo jinou hodnotu kvalifikátoru, kterou je třeba použít při hledání odpovídajícího souboru s prostředky k načtení. Můžete například chtít, aby vaši uživatelé mohli vybrat alternativní jazyk pro popisy nebo chybové zprávy.

Můžete to provést tak, že vytvoříte nový ResourceContext, přepíšete jeho hodnoty a pak použijete tento kontextový objekt ve vyhledávání řetězců.

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;

Použití hodnot kvalifikátoru, jako je uvedeno v příkladu kódu výše, funguje pro všechny kvalifikátory. V případě speciálního případu jazyka to můžete místo toho provést.

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

Načtení řetězců z knihovny tříd

Řetězcové prostředky odkazované knihovny tříd jsou obvykle přidány do podsložky balíčku, ve kterém jsou zahrnuty během procesu sestavení. Identifikátor prostředku takového řetězce obvykle má tvar "LibraryName/ResourcesFileName/ResourceIdentifier".

Knihovna může získat ResourceLoader pro vlastní prostředky. Například následující kód ukazuje, jak může knihovna nebo aplikace, která na ni odkazuje, získat ResourceLoader pro řetězcové prostředky knihovny.

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

Pokud máte pochybnosti o cestě, můžete zadat MakePri.exe možnosti příkazového řádku k výpisu souboru PRI komponenty nebo knihovny. V souboru s výpisem se zobrazí uri jednotlivých prostředků.

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

Načítání řetězců z jiných balíčků

Prostředky balíčku aplikace se spravují a k nim se přistupuje prostřednictvím vlastní mapy zdrojů (ResourceMap) nejvyšší úrovně, která je přístupná z ResourceManageru. V rámci každého balíčku můžou mít různé komponenty vlastní podstromy ResourceMap , ke kterým můžete přistupovat prostřednictvím ResourceMap.GetSubtree.

Rámcový balíček může přistupovat ke svým vlastním prostředkům pomocí absolutního URI identifikátoru prostředku. Další informace najdete také ve schématech identifikátorů URI v dokumentaci k UWP.

Načítání řetězců v nezabalených aplikacích

Od verze Windows 1903 (aktualizace z května 2019) můžou rozbalené aplikace využívat také systém správy prostředků.

Stačí vytvořit uživatelské ovládací prvky nebo knihovny sady Windows App SDK a ukládat všechny řetězce do souboru prostředků. Poté můžete odkazovat na identifikátor řetězcového prostředku zXAML, odkazovat na identifikátor řetězcového prostředku z kódunebo načítat řetězce z knihovny tříd.

Pokud chcete používat prostředky v nezabalených aplikacích, měli byste udělat několik věcí:

1. Pomocí přetíženého konstruktoru ResourceManager předejte název .pri souboru vaší aplikace při řešení prostředků z kódu, protože v nevybalených scénářích není k dispozici výchozí zobrazení.
2. Pomocí MakePri.exe ručně vygenerujte soubor resources.pri vaší aplikace.
   • Spusťte příkaz makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri.
   • <PRICONFIG> musí vynechat oddíl "<balení>", aby byly všechny prostředky zahrnuty do jediného souboru resources.pri. Pokud používáte výchozí konfigurační soubor MakePri.exe vytvořený createconfig, musíte po jeho vytvoření ručně odstranit sekci "<packaging>".
   • PRICONFIG <> musí obsahovat všechny relevantní indexery potřebné ke sloučení všech prostředků v projektu do jednoho souboru resources.pri. Výchozí konfigurační souborMakePri.exe vytvořený nástrojem createconfig zahrnuje všechny indexery.
   • Pokud nepoužíváte výchozí konfiguraci, ujistěte se, že je povolený indexer PRI (zkontrolujte výchozí konfiguraci, jak to provést) ke sloučení PRI nalezených z odkazů na projektu, odkazů NuGet atd., které jsou umístěné v kořenovém adresáři projektu.

     Poznámka:

     Vynecháním /IndexNamea tím, že projekt nemá manifest aplikace, se indexName/kořenový obor názvů souboru PRI automaticky nastaví na Application, což runtime chápe pro rozbalené aplikace (tím se odebere předchozí pevná závislost na ID balíčku). Při zadávání identifikátorů URI prostředků odkazuje ms-resource:/// na situaci, kdy je vynechán kořenový obor názvů a implicitně se považuje Application za kořenový obor názvů pro rozbalené aplikace (případně můžete zadat explicitně Application, jako se to dělá v ms-resource://Application/).

3. Zkopírujte soubor PRI do výstupního adresáře sestavení .exe
4. Spusťte .exe

   Poznámka:

   Systém správy prostředků používá jazyk zobrazení systému namísto seznamu upřednostňovaných jazyků uživatele při řešení prostředků na základě jazyka v nezabalených aplikacích. Seznam upřednostňovaných jazyků uživatele se používá jenom pro zabalené aplikace sady Windows App SDK.

Důležité

Při změně prostředků je nutné ručně znovu sestavit soubory PRI. Doporučujeme použít skript po sestavení, který zpracuje příkazMakePri.exe a zkopíruje výstup resources.pri do .exe adresáře.

Důležitá rozhraní API

• ApplicationModel.Resources.ResourceLoader

Viz také

• vzorek MRT Core
• Jak načíst řetězcové zdroje