WPF 全球化和當地語系化概觀

發行項
10/18/2023

當您將產品的可用性限制為只有一種語言時，您可以將潛在客戶群限制為全球 75 億人口的一小部分。如果您想要全球對象都可以使用應用程式，則具成本效益的產品當地語系化是更多客戶可以使用的一種最佳且最經濟的方法。

本概觀介紹 Windows Presentation Foundation （WPF）中的全球化和當地語系化。全球化是在多個位置執行之應用程式的設計和開發。例如，全球化支援不同文化特性中使用者的當地語系化使用者介面和地區資料。 WPF 提供全球化的設計功能，包括自動版面配置、附屬元件，以及當地語系化的屬性和批註。

當地語系化會將應用程式資源翻譯為應用程式所支援之特定文化特性的當地語系化版本。當您在 WPF 中當地語系化時，您會使用命名空間中的 System.Windows.Markup.Localizer API。這些 API 可增強 LocBaml 工具範例命令列工具。如需如何建置和使用 LocBaml 的資訊，請參閱將應用程式當地語系化。

警告

LocBaml 工具僅適用于適用于 .NET Framework 專案的 WPF，不適用於適用于 .NET 的 WPF。

WPF 中的全球化和當地語系化最佳做法

您可以遵循本節提供的 UI 設計和當地語系化相關秘訣，充分利用 WPF 內建的全球化和當地語系化功能。

WPF UI 設計最佳做法

設計 WPF 型 UI 時，請考慮實作下列最佳做法：

在 XAML 中撰寫 UI;避免在程式碼中建立 UI。當您使用 XAML 建立 UI 時，您會透過內建的當地語系化 API 來公開 UI。
請避免使用絕對位置和固定大小來配置內容；相反地，請使用相對或自動調整大小。
- 使用 SizeToContent ，並將寬度和高度設定為 Auto 。
- 避免使用 Canvas 來配置 UI。
- 使用 Grid 及其大小共用功能。
因為當地語系化文字通常需要更多空間，所以請在邊界提供額外空間。額外空間可放置可能突出的字元。
TextBlock啟用 TextWrapping 以避免裁剪。
設定 xml:lang 屬性。此屬性描述特定項目的文化特性和其子項目。這個屬性的值會變更 WPF 中數個功能的行為。例如，它會變更斷字、拼字檢查、數字替代、複雜指令碼形成和字型遞補的行為。如需設定 XAML 中的 xml:lang 處理的詳細資訊，請參閱 WPF 的全球化。
建立自訂的複合字型，進一步控制用於不同語言的字型。根據預設，WPF 會使用 Windows\Fonts 目錄中的 GlobalUserInterface.composite 字型。
當您建立可能以從右至左格式呈現文字之文化特性的導覽應用程式時，請明確設定 FlowDirection 每個頁面的，以確保頁面不會繼承 FlowDirection 自 NavigationWindow 。
當您建立裝載于瀏覽器外部的獨立導覽應用程式時，請將初始應用程式的設定 StartupUri 為 NavigationWindow ，而不是設定為頁面（例如 <Application StartupUri="NavigationWindow.xaml"> ）。此設計可讓您變更 FlowDirection 視窗和導覽列的。如需詳細資訊和範例，請參閱 Globalization Homepage Sample (全球化首頁範例)。

WPF 當地語系化最佳做法

當您將 WPF 型應用程式當地語系化時，請考慮實作下列最佳做法：

使用當地語系化批註為當地語系化人員提供額外的內容。
使用當地語系化屬性來控制當地語系化，而不是選擇性地 Uid 省略元素上的屬性。如需詳細資訊，請參閱當地語系化屬性和註解。
使用 msbuild -t:updateuid 和 -t:checkuid 在您的 XAML 中新增和檢查 Uid 屬性。使用 Uid 屬性來追蹤開發和當地語系化之間的變更。 Uid 屬性可協助您當地語系化新的開發變更。如果您手動將屬性新增 Uid 至 UI，工作通常很乏味且較不精確。
- 開始當地語系化之後，請勿編輯或變更 Uid 屬性。
- 請勿使用重複 Uid 的屬性（當您使用複製和貼上命令時，請記住這個提示）。
- UltimateResourceFallback設定 AssemblyInfo.* 中的位置，以指定後援的適當語言（例如， [assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)] 。
  
  如果您決定藉由省略 <UICulture> 專案檔中的標記，將來來源語言包含在主要元件中，請將 UltimateResourceFallback 位置設定為主要元件，而不是附屬元件（例如）。 [assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.MainAssembly)]

將 WPF 應用程式當地語系化

當您將 WPF 應用程式當地語系化時，您有幾個選項。例如，您可以將應用程式中的可當地語系化資源系結至 XML 檔案、將可當地語系化的文字儲存在 resx 資料表中，或讓當地語系化工具使用 XAML 檔案。本節描述使用 BAML 形式的 XAML 的當地語系化工作流程，其提供數個優點：

您可以在建置之後當地語系化。
您可以使用舊版 BAML 形式的 XAML 當地語系化，更新為較新版本的 BAML 格式 XAML，以便您同時進行開發當地語系化。
您可以在編譯時期驗證原始來源元素和語意，因為 BAML 形式的 XAML 是已編譯的 XAML 形式。

當地語系化建置程序

當您開發 WPF 應用程式時，當地語系化的建置程式如下所示：

開發人員會建立和全球化 WPF 應用程式。在專案檔中，開發人員會設定 <UICulture>en-US</UICulture> ，以便在編譯應用程式時產生語言中性的主要元件。此組件具有包含所有可當地語系化資源的附屬 .resources.dll 檔案。您可以選擇性地將來來源語言保留在主要元件中，因為我們的當地語系化 API 支援從主要元件擷取。
當檔案編譯成組建時，XAML 會轉換成 XAML 的 BAML 形式。文化中立 MyDialog.exe 性和文化上相依（英文） MyDialog.resources.dll 檔案會發行給講英語的客戶。

當地語系化工作流程

當地語系化程式會在建置未當地語系化 MyDialog.resources.dll 的檔案之後開始。原始 XAML 中的 UI 元素和屬性會使用下的 System.Windows.Markup.Localizer API，從 XAML 的 BAML 形式擷取成索引鍵/值組。當地語系化人員會使用鍵值組來當地語系化應用程式。當地語系化完成之後，即可從新值產生新的 .resource.dll。

索引鍵/值組的索引鍵是 x:Uid 開發人員在原始 XAML 中放置的值。這些 x:Uid 值可讓 API 在當地語系化期間追蹤和合併開發人員與當地語系化工具之間發生的變更。例如，如果開發人員在當地語系化工具開始當地語系化之後變更 UI，您可以將開發變更與已完成的當地語系化工作合併，讓最少的翻譯工作遺失。

下圖顯示根據 BAML 形式之 XAML 的一般當地語系化工作流程。此圖表假設開發人員會以英文撰寫應用程式。開發人員會建立和全球化 WPF 應用程式。在專案檔中，開發人員會在建置時設定 <UICulture>en-US</UICulture> 語言中性主要元件，並產生包含所有可當地語系化資源的附屬 .resources.dll。或者，有人保持主要組件中的來源語言，因為 WPF 當地語系化 API 支援從主要組件進行擷取。建置程序之後，XAML 會編譯到 BAML。與文化特性無關的 MyDialog.exe.resources.dll 會傳送給英語系的客戶。

Diagram showing the Localization workflow.

Diagram showing the Unlocalized workflow.

WPF 當地語系化範例

本節包含當地語系化應用程式的範例，可協助您瞭解如何建置和當地語系化 WPF 應用程式。

執行對話方塊範例

下圖顯示 [執行] 對話方塊範例的輸出。

英文：

Screenshot showing an English Run dialog box.

德文：

Screenshot showing a German Run dialog box.

設計全域執行對話方塊

此範例會使用 WPF 和 XAML 產生 [ 執行 ] 對話方塊。此對話方塊相當於 Microsoft Windows [開始] 功能表提供的 [執行 ] 對話方塊。

建立全域對話方塊的一些重點如下︰

自動版面配置

在 Window1.xaml 中：

<Window SizeToContent="WidthAndHeight">

前一個 Window 屬性會根據內容的大小來自動調整視窗大小。此屬性會防止視窗中在當地語系化因大小增加而裁切內容；內容在當地語系化後大小減少時，它也會移除不必要的空間。

<Grid x:Uid="Grid_1">

Uid 需要屬性，WPF 當地語系化 API 才能正常運作。

WPF 當地語系化 API 會使用它們來追蹤使用者介面（UI）開發和當地語系化之間的變更。 Uid 屬性可讓您合併較新版本的 UI 與舊版 UI 的當地語系化。您可以在命令殼層中執行 msbuild -t:updateuid RunDialog.csproj 來新增 Uid 屬性。這是新增 Uid 屬性的建議方法，因為手動新增屬性通常是耗時且較不精確。您可以執行 msbuild -t:checkuid RunDialog.csproj 來檢查 Uid 屬性是否已正確設定。

UI 是使用 Grid 控制項進行結構化，這是利用 WPF 中自動版面配置的實用控制項。請注意，對話方塊分成三個資料列和五個資料行。其中一個資料列和資料行定義沒有固定大小;因此，位於每個資料格中的 UI 元素可以適應當地語系化期間的大小增加和減少。

<Grid.ColumnDefinitions>
  <ColumnDefinition x:Uid="ColumnDefinition_1" />
  <ColumnDefinition x:Uid="ColumnDefinition_2" />

Open： label 和 ComboBox 放置的前兩個數據 行會使用 10% 的 UI 總寬度。

  <ColumnDefinition x:Uid="ColumnDefinition_3" SharedSizeGroup="Buttons" />
  <ColumnDefinition x:Uid="ColumnDefinition_4" SharedSizeGroup="Buttons" />
  <ColumnDefinition x:Uid="ColumnDefinition_5" SharedSizeGroup="Buttons" />
</Grid.ColumnDefinitions>

請注意，此範例使用的共用調整大小功能 Grid 。最後三個數據行會利用這一點，方法是將自己放在相同的 SharedSizeGroup 中。因為其中一個預期來自屬性名稱，所以這可讓資料行共用相同的大小。因此，當「Browse...」會當地語系化為較長的字串「Durchsuchen...」，所有按鈕都會以寬度成長，而不是有一個小的「OK」按鈕和不成比例的大「Durchsuchen...」。按鈕。

xml：lang

xml:lang="en-US"

請注意位於 UI 根項目之 XAML 中的 xml：lang 處理。此屬性描述所指定項目的文化特性和其子項目。這個值是由 WPF 中的數個功能所使用，而且應該在當地語系化期間適當地變更。此值可變更使用何種語言字典來進行斷字和拼字檢查。它也會影響顯示的位數，以及字型遞補系統如何選取要使用的字型。最後，此屬性會影響數字顯示方式，以及使用複雜指令碼所撰寫之文字的形成方式。預設值是 "en-US"。

建置附屬資源組件

在 .csproj 中：

編輯檔案， .csproj 並將下列標籤新增至無條件 <PropertyGroup> ：

<UICulture>en-US</UICulture>

請注意加入 UICulture 值。當此值設定為有效 CultureInfo 值，例如 en-US 時，建置專案會產生具有所有可當地語系化資源的附屬元件。

<Resource Include="RunIcon.JPG">

<Localizable>False</Localizable>

</Resource>

RunIcon.JPG不需要當地語系化，因為它應該在所有文化特性中看起來都相同。 Localizable 設定為 false ，使其維持在語言中性主要元件中，而不是附屬元件。所有不可編譯資源的 Localizable 預設值會設定為 true 。

將執行對話方塊當地語系化

剖析

建置應用程式之後，將它當地語系化的第一個步驟是剖析附屬組件的可當地語系化資源。基於本主題的目的，請使用 LocBaml 工具範例中提供的 LocBaml 範例工具。請注意，LocBaml 只是一種範例工具，旨在協助您開始建置符合當地語系化程序的當地語系化工具。使用 LocBaml，執行下列命令來進行剖析︰LocBaml /parse RunDialog.resources.dll /out: 以產生 "RunDialog.resources.dll.CSV" 檔案。

警告

LocBaml 工具僅適用于適用于 .NET Framework 專案的 WPF，不適用於適用于 .NET 的 WPF。

當地語系化

使用支援 Unicode 的慣用 CSV 編輯器，才能編輯這個檔案。篩選出當地語系化分類為 "None" 的所有項目。您應該會看到下列項目：

資源索引鍵	當地語系化分類	值
Button_1:System.Windows.Controls.Button.$Content	Button	確定
Button_2:System.Windows.Controls.Button.$Content	Button	取消
Button_3:System.Windows.Controls.Button.$Content	Button	瀏覽...
ComboBox_1:System.Windows.Controls.ComboBox.$Content	ComboBox
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Text	輸入程式、資料夾、文件或網際網路資源的名稱，Windows 會自動開啟。
TextBlock_2:System.Windows.Controls.TextBlock.$Content	Text	開啟：
Window_1:System.Windows.Window.Title	標題	執行

將應用程式當地語系化為德文需要下列翻譯︰

資源索引鍵	當地語系化分類	值
Button_1:System.Windows.Controls.Button.$Content	Button	確定
Button_2:System.Windows.Controls.Button.$Content	Button	Abbrechen
Button_3:System.Windows.Controls.Button.$Content	Button	Durchsuchen…
ComboBox_1:System.Windows.Controls.ComboBox.$Content	ComboBox
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Text	Geben Sie den Namen eines Programms, Ordners, Dokuments oder einer Internetresource an.
TextBlock_2:System.Windows.Controls.TextBlock.$Content	Text	Öffnen：
Window_1:System.Windows.Window.Title	標題	執行

產生

當地語系化的最後一個步驟包括建立新的當地語系化附屬組件。使用下列 LocBaml 命令，即可完成這項作業：

LocBaml.exe /generate RunDialog.resources.dll /trans：RunDialog.resources.dll.CSV /out：。 /cul：de-DE

在德文 Windows 上，如果此 resources.dll 放在主要元件旁邊的 de-DE 資料夾中，則此資源會自動載入，而不是 en-US 資料夾中的 de-US 資料夾。如果您沒有德文版本的 Windows 來測試此專案，請將文化特性設定為您使用的任何 Windows 文化特性（例如 en-US ），並取代原始資源 DLL。

附屬資源載入

MyDialog.exe	en-US\MyDialog.resources.dll	de-DE\MyDialog.resources.dll
代碼	附屬資源 BAML	當地語系化 BAML
文化特性中性資源	英文的其他資源	當地語系化為德文的其他資源

.NET 會自動根據應用程式的 Thread.CurrentUICulture 選擇要載入的附屬資源元件。這會預設為 Windows OS 的文化特性。如果您使用德文 Windows，de-DE \MyDialog.resources.dll 檔案會載入。如果您使用英文 Windows，en-US \MyDialog.resources.dll 檔案會載入。您可以在專案的 AssemblyInfo 檔案中指定 NeutralResourcesLanguage 屬性，以設定應用程式的最終後援資源。例如，如果您指定：

[assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)]

如果下列兩個檔案都無法使用，則 en-US\MyDialog.resources.dll 檔案會與德文 Windows 搭配使用： de-DE\MyDialog.resources.dll 或 de\MyDialog.resources.dll 。

Microsoft Saudi Arabia 首頁

下圖顯示英文和阿拉伯文首頁。如需詳細資訊和範例，請參閱 Globalization Homepage Sample (全球化首頁範例)。

英文：

Screenshot showing an English home page.

阿拉伯文：

Screenshot showing an Arabic home page.

設計全域 Microsoft 首頁

這個模擬的 Microsoft Saudi Arabia 網站說明針對 RightToLeft 語言所提供的全球化功能。希伯來文和阿拉伯文等語言都有由右至左讀取順序，因此 UI 的配置通常與英文等由左至右的語言配置大不相同。從由左至右語言當地語系化為由右至左語言 (反之亦然) 可能相當困難。 WPF 的設計目的是讓這類當地語系化更容易。

FlowDirection

Homepage.xaml：

<Page x:Uid="Page_1" x:Class="MicrosoftSaudiArabiaHomepage.Homepage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"   
    FlowDirection="LeftToRight" 
    Localization.Comments="FlowDirection(This FlowDirection controls the actual content of the homepage)"
    xml:lang="en-US">

請注意上的 FlowDirection Page 屬性。將此屬性變更為 RightToLeft 會變更 FlowDirection 及其子項目的 Page ，如此一來，此 UI 的版面配置就會變成由右至左，就像阿拉伯使用者預期的那樣。您可以藉由在任何專案上指定明確的 FlowDirection 來覆寫繼承行為。屬性 FlowDirection 可在任何 FrameworkElement 或檔相關專案上使用，且具有的隱含值 LeftToRight 。

請注意，變更根 FlowDirection 目錄時，即使是背景漸層筆刷也會正確翻轉：

FlowDirection="LeftToRight"

Screenshot showing the gradient flow from left to right.

FlowDirection="RightToLeft"

Screenshot showing the gradient flow from right to left.

避免面板和控制項使用固定維度

查看 Homepage.xaml，請注意，除了為上方 DockPanel 的整個 UI 指定的固定寬度和高度之外，沒有其他固定尺寸。請避免使用固定維度，防止裁剪長度超過來源文字的當地語系化文字。 WPF 面板和控制項將根據其包含的內容自動調整大小。大部分的控制項也有您可以為更多控制項設定的最小和最大維度（例如 MinWidth=「20」。使用 Grid ，您也可以使用 '*' Width="0.25*" 來設定相對寬度和高度，或使用其儲存格大小共用功能。

當地語系化註解

在許多情況下，內容可能會模稜兩可，而不容易翻譯。開發人員或設計人員可以透過當地語系化註解來提供額外內容和註解。例如，以下的 Localization.Comments 會厘清字元 '|' 的使用方式。

<TextBlock 
  x:Uid="TextBlock_2" 
  DockPanel.Dock="Right" 
  Foreground="White" 
  Margin="5,0,5,0"
  Localization.Comments="$Content(This character is used as a decorative rule.)">
  |
</TextBlock>

此批註會與TextBlock_1的內容相關聯，並在 LocBaml 工具的情況下，于輸出 .csv 檔案中TextBlock_1列的第 6 欄看到：

資源索引鍵	類別	可讀取	可修改	註解	值
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Text	TRUE	TRUE	此字元是當成裝飾規則使用。	\|

使用下列語法，可以放入任何項目之內容或屬性的註解︰

<TextBlock 
  x:Uid="TextBlock_1" 
  DockPanel.Dock="Right" 
  Foreground="White" 
  Margin="5,0,5,0"
  Localization.Comments="$Content(This is a comment on the TextBlock's content.)
     Margin(This is a comment on the TextBlock's Margin property.)">
  |
 </TextBlock>

當地語系化屬性

開發人員或當地語系化管理員通常需要控制當地語系化人員可以讀取和修改的內容。例如，您可能不想要當地語系化人員翻譯公司名稱或法律用語。 WPF 提供屬性，可讓您設定元素內容或屬性的可讀性、可修改性和類別，而當地語系化工具可用來鎖定、隱藏或排序元素。如需詳細資訊，請參閱Attributes。基於此範例的目的，LocBaml 工具只會輸出這些屬性的值。 WPF 控制項都有這些屬性的預設值，但您可以覆寫它們。例如，下列範例會覆寫的預設 TextBlock_1 當地語系化屬性，並將內容設定為可讀取，但無法修改當地語系化人員的內容。

<TextBlock
x:Uid="TextBlock_1"
Localization.Attributes=
"$Content(Readable Unmodifiable)">
  Microsoft Corporation
</TextBlock>

除了可讀性和可修改性屬性之外，WPF 還提供通用 UI 類別（ LocalizationCategory ）的列舉，可用來為當地語系化人員提供更多內容。您也可以在 XAML 中覆寫平臺控制項的 WPF 預設類別：

<TextBlock x:Uid="TextBlock_2">
<TextBlock.ToolTip>
<TextBlock
x:Uid="TextBlock_3"
Localization.Attributes=
"$Content(ToolTip Readable Unmodifiable)">
Microsoft Corporation
</TextBlock>
</TextBlock.ToolTip>
Windows Vista
</TextBlock>

WPF 提供的預設當地語系化屬性也可以透過程式碼覆寫，因此您可以正確設定自訂控制項的正確預設值。例如：

[Localizability(Readability = Readability.Readable, Modifiability=Modifiability.Unmodifiable, LocalizationCategory.None)]
public class CorporateLogo : TextBlock
{
    // ...
}

XAML 中設定的每個實例屬性，將優先于自訂控制項上程式碼中設定的值。如需屬性和註解的詳細資訊，請參閱當地語系化屬性和註解。

字型遞補和複合字型

如果您指定不支援指定之程式碼點範圍的字型，WPF 會自動回復至使用位於 Windows\Fonts 目錄中的全域使用者介面.compositefont 所執行的字型。複合字型的運作方式就像任何其他字型一樣，而且可以藉由設定元素的 FontFamily 來明確使用（例如， FontFamily="Global User Interface" 。建立您自己的複合字型並指定要用於特定字碼指標範圍和語言的字型，即可指定自己的字型遞補喜好設定。

如需複合字型的詳細資訊，請參閱 FontFamily 。

將 Microsoft 首頁當地語系化

您可以遵循「執行對話方塊」範例中的相同步驟，將此應用程式當地語系化。 Globalization Homepage Sample (全球化首頁範例) 中提供阿拉伯文的當地語系化 .csv 檔案。

共用方式為