Xamarin.Forms Lokalizace řetězců a obrázků

  • Článek

Lokalizace je proces přizpůsobení aplikace tak, aby splňovala konkrétní jazykové nebo kulturní požadavky cílového trhu. Aby bylo možné dosáhnout lokalizace, může být nutné text a obrázky v aplikaci přeložit do více jazyků. Lokalizovaná aplikace automaticky zobrazí přeložený text na základě nastavení jazykové verze mobilního zařízení:

Snímky obrazovky lokalizační aplikace v iOSu a Androidu

Rozhraní .NET Framework obsahuje integrovaný mechanismus pro lokalizaci aplikací pomocí souborů prostředků Resx. Soubor prostředků ukládá text a další obsah jako dvojice název/hodnota, které aplikaci umožňují načíst obsah zadaného klíče. Soubory prostředků umožňují oddělit lokalizovaný obsah od kódu aplikace.

Použití souborů prostředků k lokalizaci Xamarin.Forms aplikací vyžaduje, abyste provedli následující kroky:

  1. Vytvořte soubory Resx obsahující přeložený text.
  2. Zadejte výchozí jazykovou verzi ve sdíleném projektu.
  3. Lokalizovat text v Xamarin.Formssouboru .
  4. Lokalizace imagí na základě nastavení jazykové verze pro každou platformu
  5. Lokalizace názvu aplikace na každé platformě
  6. Otestujte lokalizaci na jednotlivých platformách.

Vytvoření souborů Resx

Soubory prostředků jsou soubory XML s příponou .resx kompilované do souborů binárních prostředků (.resources) během procesu sestavení. Visual Studio 2019 vygeneruje třídu, která poskytuje rozhraní API sloužící k načtení prostředků. Lokalizovaná aplikace obvykle obsahuje výchozí soubor prostředků se všemi řetězci používanými v aplikaci a soubory prostředků pro každý podporovaný jazyk. Ukázková aplikace má ve sdíleném projektu složku Resx , která obsahuje soubory prostředků, a její výchozí soubor prostředků s názvem AppResources.resx.

Soubory prostředků obsahují pro každou položku následující informace:

  • Název určuje klíč použitý pro přístup k textu v kódu.
  • Hodnota určuje přeložený text.
  • Komentář je volitelné pole obsahující další informace.

Soubor prostředku se přidá pomocí dialogového okna Přidat novou položku v sadě Visual Studio 2019:

Přidání nového prostředku v sadě Visual Studio 2019

Po přidání souboru je možné přidat řádky pro každý textový prostředek:

Zadání výchozích textových prostředků v souboru .resx

Nastavení rozevíracího seznamu Modifikátor přístupu určuje, jak Visual Studio generuje třídu použitou pro přístup k prostředkům. Nastavení modifikátoru přístupu na veřejné nebo interní výsledky ve vygenerované třídě se zadanou úrovní přístupnosti. Nastavení modifikátoru přístupu na hodnotu Bez generování kódu negeneruje soubor třídy. Výchozí soubor prostředků by měl být nakonfigurovaný tak, aby vygeneroval soubor třídy, což vede k souboru s příponou .designer.cs přidanou do projektu.

Po vytvoření výchozího souboru prostředků je možné vytvořit další soubory pro každou jazykovou verzi, kterou aplikace podporuje. Každý další soubor prostředků by měl v názvu souboru obsahovat jazykovou verzi překladu a měl by mít modifikátor přístupu nastavený na žádné generování kódu.

Za běhu se aplikace pokusí vyřešit požadavek na prostředek v pořadí specificity. Pokud je například jazyková verze zařízení en-US , aplikace hledá soubory prostředků v tomto pořadí:

  1. AppResources.en-US.resx
  2. AppResources.cs.resx
  3. AppResources.resx (výchozí)

Následující snímek obrazovky ukazuje soubor pro překlad španělštiny s názvem AppResources.es.resx:

Zadání výchozích textových prostředků španělštiny v souboru .resx

Soubor překladu používá stejné hodnoty Name zadané ve výchozím souboru, ale obsahuje řetězce španělštiny ve sloupci Hodnota . Modifikátor přístupu je navíc nastavený na žádné generování kódu.

Soubor prostředku se přidá pomocí dialogového okna Přidat nový soubor v sadě Visual Studio 2019 pro Mac:

Přidání nového prostředku v sadě Visual Studio 2019 pro Mac

Po vytvoření výchozího souboru prostředků lze text přidat vytvořením data prvků v root elementu v souboru prostředků:

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="AddButton" xml:space="preserve">
        <value>Add Note</value>
    </data>
    <data name="NotesLabel" xml:space="preserve">
        <value>Notes:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>e.g. Get Milk</value>
    </data>
</root>

Soubor třídy .designer.cs lze vytvořit nastavením vlastnosti Vlastní nástroj v možnostech souboru prostředků:

Vlastní nástroj zadaný ve vlastnostech souboru prostředků

Nastavení vlastního nástroje na PublicResXFileCodeGenerator způsobí vygenerovanou třídu s public přístupem. Nastavení vlastního nástroje na InternalResXFileCodeGenerator způsobí vygenerovanou třídu s internal přístupem. Prázdná hodnota vlastního nástroje nevygeneruje třídu. Vygenerovaný název třídy bude odpovídat názvu souboru prostředku. Například soubor AppResources.resx způsobí vytvoření AppResources třídy v souboru s názvem AppResources.designer.cs.

Pro každou podporovanou jazykovou verzi je možné vytvořit další soubory prostředků. Každý soubor jazyka by měl v názvu souboru obsahovat jazykovou verzi překladu, aby měl název AppResources.es-MX.resx.

Za běhu se aplikace pokusí vyřešit požadavek na prostředek v pořadí specificity. Pokud je například jazyková verze zařízení en-US , aplikace hledá soubory prostředků v tomto pořadí:

  1. AppResources.en-US.resx
  2. AppResources.cs.resx
  3. AppResources.resx (výchozí)

Soubory překladu jazyka by měly mít stejné hodnoty názvu jako výchozí soubor. Následující kód XML ukazuje soubor pro překlad španělštiny s názvem AppResources.es.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="NotesLabel" xml:space="preserve">
        <value>Notas:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>por ejemplo . comprar leche</value>
    </data>
    <data name="AddButton" xml:space="preserve">
        <value>Agregar nuevo elemento</value>
    </data>
</root>

Určení výchozí jazykové verze

Aby soubory prostředků fungovaly správně, musí mít NeutralResourcesLanguage aplikace zadaný atribut. V projektu obsahujícím soubory zdrojů by měl být soubor AssemblyInfo.cs přizpůsoben tak, aby určil výchozí jazykovou verzi. Následující kód ukazuje, jak nastavit NeutralResourcesLanguage hodnotu en-US v souboru AssemblyInfo.cs :

using System.Resources;

// The resources from the neutral language .resx file are stored directly
// within the library assembly. For that reason, changing en-US to a different
// language in this line will not by itself change the language shown in the
// app. See the discussion of UltimateResourceFallbackLocation in the
// documentation for additional information:
// https://learn.microsoft.com/dotnet/api/system.resources.neutralresourceslanguageattribute
[assembly: NeutralResourcesLanguage("en-US")]

Upozorňující

Pokud atribut nezadáte NeutralResourcesLanguage , ResourceManager třída vrátí null hodnoty pro všechny jazykové verze bez konkrétního souboru prostředků. Pokud je zadána výchozí jazyková verze, ResourceManager vrátí výsledky z výchozího souboru Resx pro nepodporované jazykové verze. Proto doporučujeme vždy určit NeutralResourcesLanguage , aby se text zobrazoval pro nepodporované jazykové verze.

Jakmile se vytvoří výchozí soubor prostředků a výchozí jazyková verze zadaná v souboru AssemblyInfo.cs , aplikace může za běhu načíst lokalizované řetězce.

Další informace o souborech prostředků najdete v tématu Vytváření souborů prostředků pro aplikace .NET.

Určení podporovaných jazyků v iOSu

V iOSu musíte deklarovat všechny podporované jazyky v souboru Info.plist pro váš projekt. V souboru Info.plist nastavte pole pro CFBundleLocalizations klíč pomocí zobrazení Zdroj a zadejte hodnoty, které odpovídají souborům Resx. Kromě toho se ujistěte, že jste pomocí klíče nastavili očekávaný jazyk CFBundleDevelopmentRegion :

Snímek obrazovky s editorem Info.plist zobrazující část Lokalizace

Případně otevřete soubor Info.plist v editoru XML a přidejte následující:

<key>CFBundleLocalizations</key>
<array>
    <string>de</string>
    <string>es</string>
    <string>fr</string>
    <string>ja</string>
    <string>pt</string> <!-- Brazil -->
    <string>pt-PT</string> <!-- Portugal -->
    <string>ru</string>
    <string>zh-Hans</string>
    <string>zh-Hant</string>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>

Poznámka:

Apple zachází s portugalštinou trochu jinak, než byste mohli očekávat. Další informace naleznete v tématu Přidání jazyků na developer.apple.com.

Další informace naleznete v tématu Určení výchozích a podporovaných jazyků v souboru Info.plist.

Určení podporovaných jazyků v UPW

To je nutné pouze v případě, že vygenerujete sadu aplikací při zabalení aplikace pro zkušební načtení nebo obchod. Když vygenerujete sadu aplikací pro UPW, při instalaci sady prostředků se načtou jenom prostředky související s nastavením jazyka instalačního zařízení. Pokud má zařízení jenom angličtinu, nainstalují se s aplikací jenom anglické prostředky. Další informace a pokyny najdete v aplikacích pro Windows 8.1 Store: Ujistěte se, že jsou na zařízení nainstalované prostředky bez ohledu na to, jestli je zařízení vyžaduje.

Lokalizace textu v Xamarin.Forms

Text je lokalizován pomocí Xamarin.Forms vygenerované AppResources třídy. Tato třída je pojmenována na základě výchozího názvu souboru prostředku. Vzhledem k tomu, že ukázkový soubor prostředků projektu má název AppResources.resx, Visual Studio vygeneruje odpovídající třídu s názvem AppResources. Statické vlastnosti jsou generovány ve AppResources třídě pro každý řádek v souboru prostředků. Ve třídě ukázkové aplikace AppResources se vygenerují následující statické vlastnosti:

  • Addbutton
  • NotesLabel
  • NotesPlaceholder

Přístup k těmto hodnotám jako x:Static umožňuje zobrazení lokalizovaného textu v xaml:

<ContentPage ...
             xmlns:resources="clr-namespace:LocalizationDemo.Resx">
    <Label Text="{x:Static resources:AppResources.NotesLabel}" />
    <Entry Placeholder="{x:Static resources:AppResources.NotesPlaceholder}" />
    <Button Text="{x:Static resources:AppResources.AddButton}" />
</ContentPage>

Lokalizovaný text lze také načíst v kódu:

public LocalizedCodePage()
{
    Label notesLabel = new Label
    {
        Text = AppResources.NotesLabel,
        // ...
    };

    Entry notesEntry = new Entry
    {
        Placeholder = AppResources.NotesPlaceholder,
        //...
    };

    Button addButton = new Button
    {
        Text = AppResources.AddButton,
        // ...
    };

    Content = new StackLayout
    {
        Children = {
            notesLabel,
            notesEntry,
            addButton
        }
    };
}

Vlastnosti ve AppResources třídě používají aktuální hodnotu System.Globalization.CultureInfo.CurrentUICulture souboru prostředků jazykové verze k načtení hodnot.

Lokalizace obrázků

Kromě ukládání textu můžou soubory Resx ukládat více než jen text, můžou také ukládat obrázky a binární data. Mobilní zařízení ale mají celou řadu velikostí a hustot a každá mobilní platforma má funkce pro zobrazování obrázků závislých na hustotě. Funkce lokalizace imagí platformy by proto měla být použita místo ukládání obrázků do souborů prostředků.

Lokalizace obrázků v Androidu

V Androidu se lokalizované kreslitelné (obrázky) ukládají pomocí konvence vytváření názvů pro složky v adresáři Resources . Složky mají název drawable s příponou pro cílový jazyk. Například složka španělštiny má název drawable-es.

Pokud je vyžadován čtyřmísmenný kód národního prostředí, android vyžaduje další r za pomlčkou. Například složka národního prostředí Mexika (es-MX) by měla mít název drawable-es-rMX. Názvy souborů obrázků v každé složce národního prostředí by měly být identické:

Lokalizované obrázky v projektu Android

Další informace naleznete v tématu Lokalizace Androidu.

Lokalizace imagí v iOSu

V iOSu se lokalizované obrázky ukládají pomocí konvence pojmenování složek v adresáři Resources . Výchozí složka má název Base.lproj. Složky specifické pro jazyk jsou pojmenované s názvem jazyka nebo národního prostředí, za kterým následuje .lproj. Například složka se španělštinou má název es.lproj.

Místní kódy se čtyřmi písmeny fungují stejně jako dvoumísmenné kódy jazyka. Například složka národního prostředí Mexiko (es-MX) by měla mít název es-MX.lproj. Názvy souborů obrázků v každé složce národního prostředí by měly být identické:

Lokalizované obrázky v projektu iOS

Poznámka:

iOS podporuje vytvoření lokalizovaného katalogu prostředků místo použití struktury složek .lproj. Musí se ale vytvořit a spravovat v Xcode.

Další informace naleznete v tématu Lokalizace iOS.

Lokalizace imagí v UPW

V UPW se lokalizované obrázky ukládají pomocí konvence pojmenování pro složky v adresáři Assets/Images . Složky jsou pojmenované pomocí jazyka nebo národního prostředí. Například složka se španělštinou má název es a složka národního prostředí Mexiko by měla mít název es-MX. Názvy souborů obrázků v každé složce národního prostředí by měly být identické:

Lokalizované obrázky v projektu UPW

Další informace naleznete v tématu Lokalizace UPW.

Využívání lokalizovaných obrázků

Vzhledem k tomu, že každá platforma ukládá obrázky s jedinečnou strukturou souborů, XAML používá OnPlatform třídu k nastavení ImageSource vlastnosti na základě aktuální platformy:

<Image>
    <Image.Source>
        <OnPlatform x:TypeArguments="ImageSource">
            <On Platform="iOS, Android" Value="flag.png" />
            <On Platform="UWP" Value="Assets/Images/flag.png" />
        </OnPlatform>
    </Image.Source>
</Image>

Poznámka:

Rozšíření OnPlatform značek nabízí stručnější způsob zadávání hodnot specifických pro platformu. Další informace naleznete v tématu OnPlatform markup extension.

Zdroj image lze nastavit na Device.RuntimePlatform základě vlastnosti v kódu:

string imgSrc = Device.RuntimePlatform == Device.UWP ? "Assets/Images/flag.png" : "flag.png";
Image flag = new Image
{
    Source = ImageSource.FromFile(imgSrc),
    WidthRequest = 100
};

Lokalizace názvu aplikace

Název aplikace je určen pro jednotlivé platformy a nepoužívá soubory prostředků Resx. Pokud chcete lokalizovat název aplikace v Androidu, přečtěte si téma Lokalizace názvu aplikace v Androidu. Pokud chcete lokalizovat název aplikace v iOSu, přečtěte si téma Lokalizace názvu aplikace v iOSu. Pokud chcete lokalizovat název aplikace v UPW, přečtěte si téma Lokalizace řetězců v manifestu balíčku UPW.

Lokalizace testů

Lokalizace testování se nejlépe dosahuje změnou jazyka zařízení. Je možné nastavit hodnotu System.Globalization.CultureInfo.CurrentUICulture v kódu, ale chování je nekonzistentní napříč platformami, takže se nedoporučuje pro testování.

V iOSu můžete v aplikaci nastavení nastavit jazyk pro každou aplikaci speciálně beze změny jazyka zařízení.

V Androidu se při spuštění aplikace detekuje a ukládá do mezipaměti nastavení jazyka. Pokud změníte jazyky, možná budete muset aplikaci ukončit a restartovat, abyste viděli použité změny.