Xamarin.Forms 字串和影像當地語系化

發行項
11/01/2019

當地語系化是調整應用程式以符合目標市場特定語言或文化需求的程式。若要完成當地語系化，應用程式中的文字和影像可能需要翻譯成多種語言。當地語系化應用程式會根據行動裝置的文化特性設定自動顯示翻譯文字：

iOS 和 Android 上當地語系化應用程式的螢幕快照

.NET Framework 包含內建機制，可用於使用 Resx 資源檔案將應用程式當地語系化。資源檔會將文字和其他內容儲存為名稱/值組，讓應用程式擷取所提供密鑰的內容。資源檔案允許當地語系化的內容與應用程式程式代碼分開。

使用資源檔案將應用程式本地化 Xamarin.Forms 需要您執行下列步驟：

建立包含翻譯文字的 Resx 檔案。
在共享專案中指定預設文化特性。
將中的 Xamarin.Forms文字當地語系化。
根據每個平臺的文化特性設定將影像當地語系化。
在每個平臺上當地語系化應用程式名稱。
在每個平台上測試當地語系化。

建立 Resx 檔案

資源檔是擴展名為 .resx 的 XML 檔案，會在建置程式期間編譯成二進位資源（.resources）檔案。 Visual Studio 2019 會產生類別，以提供用來擷取資源的 API。本地化的應用程式通常會包含預設資源檔，其中包含應用程式中使用的所有字串，以及每個支援語言的資源檔。範例應用程式在包含資源檔的共享專案中具有 Resx 資料夾，以及其預設資源檔，稱為 AppResources.resx。

資源檔案包含每個專案的下列資訊：

名稱會指定用來存取程式代碼中文字的索引鍵。
值會指定翻譯的文字。
批註是包含其他信息的選擇性欄位。

Visual Studio 2019 中的 [新增專案] 對話框會新增資源檔：

在 Visual Studio 2019 中新增資源

一旦新增檔案，就可以為每個文字資源新增數據列：

在 .resx 檔案中指定預設文字資源

Access 修飾詞 下拉式清單設定會決定Visual Studio如何產生用來存取資源的類別。將 Access 修飾詞設定為 Public 或 Internal ，會產生具有指定輔助功能層級的產生類別。將 Access 修飾詞設定為 [無程式代碼產生 ] 不會產生類別檔案。默認資源文件應該設定為產生類別檔案，這會導致將.designer.cs擴展名新增至專案的檔案。

建立預設資源檔案之後，應用程式支援的每個文化特性都可以建立其他檔案。每個額外的資源檔都應該在檔名中包含翻譯文化特性，而且應該將 Access 修飾詞 設定為 [無程式代碼產生]。

在運行時間，應用程式會嘗試依特定順序解析資源要求。例如，如果裝置文化特性為 en-US ，應用程式會依下列順序尋找資源檔：

AppResources.en-US.resx
AppResources.en.resx
AppResources.resx （預設值）

下列螢幕快照顯示名為 AppResources.es.resx 的西班牙文翻譯檔案：

在 .resx 檔案中指定預設西班牙文文字資源

翻譯檔案會使用預設檔案中指定的相同 Name 值，但在 Value 資料行中包含西班牙文語言字串。此外， Access 修飾詞 會設定為 [無程式代碼產生]。

Visual Studio 2019 for Mac 中的 [新增檔案] 對話框會新增 資源文件 ：

在 Visual Studio 2019 for Mac 中新增資源

建立預設資源檔案之後，即可在資源檔內的元素內root建立data元素來新增文字：

<?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>

您可以在資源檔案選項設定自訂工具屬性，以建立.designer.cs類別檔案：

資源檔案屬性中指定的自訂工具

將 自訂工具 設定為 PublicResXFileCodeGenerator 會導致產生具有存取權的 public 類別。將 自訂工具 設定為 InternalResXFileCodeGenerator 會導致產生具有存取權 internal 的類別。空 的自定義工具 值不會產生類別。產生的類別名稱會符合資源檔案名稱。例如，AppResources.resx 檔案會導致在名為 AppResources.designer.cs 的檔案中建立AppResources類別。

您可以為每個支援的文化特性建立其他資源檔。每個語言檔案都應該在檔名中包含翻譯文化特性，因此以 es-MX 為目標的檔案應該命名為 AppResources.es-MX.resx。

在運行時間，應用程式會嘗試依特定順序解析資源要求。例如，如果裝置文化特性為 en-US ，應用程式會依下列順序尋找資源檔：

AppResources.en-US.resx
AppResources.en.resx
AppResources.resx （預設值）

語言翻譯檔案應該具有與預設檔案相同的 Name 值。下列 XML 顯示名為 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>

指定預設文化特性

若要讓資源檔案正常運作，應用程式必須指定 NeutralResourcesLanguage 屬性。在包含資源檔的專案中， 應該自定義AssemblyInfo.cs 檔案來指定預設文化特性。下列程式代碼示範如何在 AssemblyInfo.cs 檔案中將設定NeutralResourcesLanguage為 en-US：

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")]

警告

如果您未指定 NeutralResourcesLanguage 屬性，類別 ResourceManager 會傳回 null 任何沒有特定資源檔之文化特性的值。指定預設文化特性時，會 ResourceManager 針對不支援的文化特性傳回預設 Resx 檔案的結果。因此，建議您一律指定 NeutralResourcesLanguage ，以便針對不支援的文化特性顯示文字。

建立預設資源檔以及AssemblyInfo.cs檔案中指定的預設文化特性之後，應用程式就可以在運行時間擷取本地化的字串。

如需資源檔的詳細資訊，請參閱建立 .NET 應用程式的資源檔。

在 iOS 上指定支持的語言

在 iOS 上，您必須在專案的 Info.plist 檔案中宣告所有支持的語言。在 Info.plist 檔案中，使用 Source 檢視來設定索引鍵的CFBundleLocalizations數位，並提供對應至 Resx 檔案的值。此外，請確定您透過 CFBundleDevelopmentRegion 索引鍵設定預期的語言：

Info.plist 編輯器的螢幕快照，其中顯示 [本地化] 區段

或者，在 XML 編輯器中開啟 Info.plist 檔案，然後新增下列內容：

<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>

注意

蘋果對待葡萄牙人的方式與你可能預期的略有不同。如需詳細資訊，請參閱在 developer.apple.com 上新增語言。

如需詳細資訊，請參閱在 Info.plist 中指定預設和支持的語言。

在UWP上指定支持的語言

只有在您封裝應用程式以進行側載或市集時，才需要產生應用程式套件組合。當您產生 UWP App 套件組合時，安裝套件組合時，它只會載入與安裝裝置語言設定相關的資源。因此，如果裝置只有英文，則只有英文資源會隨應用程式一起安裝。如需詳細資訊和指示，請參閱 Windows 8.1 市集應用程式：確定無論裝置是否需要資源，都安裝在裝置上。

在中本地化文字 Xamarin.Forms

文字會使用產生的AppResources類別進行當地語系化Xamarin.Forms。此類別是以預設資源檔名稱為基礎來命名。由於範例專案資源檔名為 AppResources.resx，因此 Visual Studio 會產生名為的 AppResources相符類別。靜態屬性會在類別中 AppResources 針對資源檔中的每個數據列產生。下列靜態屬性會在範例應用程式的 AppResources 類別中產生：

AddButton
NotesLabel
NotesPlaceholder

以 x：Static 屬性的形式存取這些值，可讓當地語系化文字顯示在 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>

您也可以在程式代碼中擷取本地化的文字：

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
        }
    };
}

類別中的 AppResources 屬性會使用的目前值 System.Globalization.CultureInfo.CurrentUICulture 來判斷要從中擷取值的文化特性資源檔。

將影像當地語系化

除了儲存文字之外，Resx 檔案還能夠只儲存文字，也可以儲存影像和二進位數據。不過，行動裝置有一系列螢幕大小和密度，而且每個行動平臺都有顯示密度相依影像的功能。因此，應該使用平臺映像當地語系化功能，而不是將映像儲存在資源檔中。

將Android上的影像當地語系化

在 Android 上，本地化的可繪製專案（images）會使用 Resources 目錄中資料夾的命名慣例來儲存。資料夾會以目標語言的後綴命名為可繪製。例如，西班牙文資料夾的名稱為 drawable-es。

需要四個字母的地區設定程式碼時，Android 在破折號之後需要額外的 r 。例如，墨西哥地區設定（es-MX）資料夾應該命名為 drawable-es-rMX。每個地區設定資料夾中的映像檔名稱應該相同：

Android 專案中的當地語系化影像

如需詳細資訊，請參閱 Android 當地語系化。

將iOS上的影像當地語系化

在iOS上，當地語系化映像會使用Resources目錄中資料夾的命名慣例來儲存。默認資料夾名為 Base.lproj。語言特定的資料夾會以語言或地區設定名稱命名，後面接著 .lproj。例如，西班牙文資料夾的名稱為 es.lproj。

四個字母的本地代碼的運作就像兩個字母的語言代碼。例如，墨西哥地區設定（es-MX）資料夾應該命名為 es-MX.lproj。每個地區設定資料夾中的映像檔名稱應該相同：

iOS 專案中的當地語系化影像

注意

iOS 支援建立本地化的資產目錄，而不是使用 .lproj 資料夾結構。不過，這些必須在 Xcode 中建立和管理。

如需詳細資訊，請參閱 iOS 當地語系化。

將UWP上的影像當地語系化

在UWP上，當地語系化的影像會使用 Assets/Images 目錄中資料夾的命名慣例來儲存。資料夾會以語言或地區設定命名。例如，西班牙文資料夾的名稱為 es ，而墨西哥地區設定資料夾應命名為 es-MX。每個地區設定資料夾中的映像檔名稱應該相同：

UWP 專案中的當地語系化影像

如需詳細資訊，請參閱 UWP 當地語系化。

取用本地化的影像

由於每個平臺都會儲存具有唯一檔案結構的影像，因此 XAML 會使用 OnPlatform 類別來根據目前的平台來設定 ImageSource 屬性：

<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>

注意

標記 OnPlatform 延伸提供更簡潔的方式來指定平臺特定值。如需詳細資訊，請參閱 OnPlatform 標記延伸。

映射來源可以根據程式代碼中的屬性來設定 Device.RuntimePlatform ：

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

將應用程式名稱當地語系化

應用程式名稱是為每個平臺指定，且不使用 Resx 資源檔。若要在 Android 上當地語系化應用程式名稱，請參閱在 Android 上當地語系化應用程式名稱。若要在 iOS 上當地語系化應用程式名稱，請參閱在 iOS 上當地語系化應用程式名稱。若要在 UWP 上當地語系化應用程式名稱，請參閱將 UWP 套件指令清單中的字串本地化。

測試當地語系化

藉由變更您的裝置語言，測試當地語系化是最佳完成的。在程式代碼中可以設定的值 System.Globalization.CultureInfo.CurrentUICulture ，但跨平台的行為不一致，因此不建議進行測試。

在 iOS 上，在設定應用程式中，您可以特別設定每個應用程式的語言，而不需變更您的裝置語言。

在 Android 上，會在應用程式啟動時偵測並快取語言設定。如果您變更語言，您可能需要結束並重新啟動應用程式，以查看套用的變更。

共用方式為