如何：將應用程式當地語系化

發行項
10/15/2024

本教學課程說明如何使用 LocBaml 工具來建立當地語系化的應用程式。

注意

LocBaml 工具不是可實際執行的應用程式。這只是個範例，示範如何使用一些當地語系化的 API，並說明如何撰寫當地語系化工具。

概觀

本文提供將應用程式當地語系化的逐步方法。首先，請準備您的應用程式，以便從中擷取要翻譯的文字。翻譯文字後，請將翻譯的文字合併至原始應用程式的新複本中。

建立應用程式範例

在此步驟中，請準備您的應用程式以進行當地語系化。在 Windows Presentation Foundation (WPF) 範例中提供了一個 HelloApp 範例，將用於此討論中的程式碼範例。如果您想要使用此範例，請從 LocBaml 工具範例下載 Extensible Application Markup Language (XAML) 檔案。

將您的應用程式開發至您要當地語系化的開始點。
在專案檔中指定開發語言，讓 MSBuild 產生主要組件和附屬組件 (副檔名為 .resources.dll 的檔案)，以包含中性語言資源。 HelloApp 範例中的專案檔是 HelloApp.csproj。在該檔案中，您會發現識別如下的開發語言：

<UICulture>en-US</UICulture>
將 UID 新增至 XAML 檔案。 UID 可用來追蹤對檔案的變更，以及識別必須轉譯的項目。若要將 UID 新增至您的檔案，請在您的專案檔上執行 updateuid：

msbuild -t:updateuid helloapp.csproj

若要確認是否有遺漏或重複的 UID，請執行 checkuid：

msbuild -t:checkuid helloapp.csproj

執行 updateuid 之後，您的檔案應該會包含 UID。例如，在 HelloApp 的 Pane1.xaml 檔案中，您應該會發現下列項目：
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

建立中性語言資源附屬組件

將應用程式設定為會產生中性語言資源附屬組件後，請建置應用程式。這會產生主要應用程式組件，以及 LocBaml 進行當地語系化所需的中性語言資源附屬組件。

若要建置應用程式：

編譯 HelloApp 以建立動態連結程式庫 (DLL)：

msbuild helloapp.csproj
新建立的主要應用程式組件 HelloApp.exe 會建立在下列資料夾中：C:\HelloApp\Bin\Debug
新建立的中性語言資源附屬組件 HelloApp.resources.dll 會建立下列資料夾中：C:\HelloApp\Bin\Debug\en-US

建置 LocBaml 工具

建置 LocBaml 時所需的所有檔案都位在 WPF 範例中。從 LocBaml 工具範例下載 C# 檔案。
從命令列執行專案檔 (locbaml.csproj)，以建置工具：

msbuild locbaml.csproj
移至 Bin\Release 目錄，尋找新建立的可執行檔 (locbaml.exe)。範例：C:\LocBaml\Bin\Release\locbaml.exe

您在執行 LocBaml 時可指定的選項如下。

選項	描述
`parse` 或 `-p`	剖析 Baml、資源或 DLL 檔案，以產生 .csv 或 .txt 檔案。
`generate` 或 `-g`	使用翻譯的檔案產生當地語系化的二進位檔案。
`out` 或 `-o` {filedirectory]	輸出檔案名稱。
`culture` 或 `-cul` {culture]	輸出組件的地區設定。
`translation` 或 `-trans` {translation.csv]	翻譯或當地語系化的檔案。
`asmpath` 或 `-asmpath` {filedirectory]	如果您的 XAML 程式碼包含自訂控制項，則必須提供 `asmpath` 給自訂控制項組件。
`nologo`	不顯示標誌或著作權資訊。
`verbose`	顯示詳細模式資訊。

注意

如果您在執行此工具時需要選項清單，請輸入 LocBaml.exe，然後按 Enter 鍵。

使用 LocBaml 來剖析檔案

現在您已經建立 LocBaml 工具，就準備好用它來剖析 HelloApp.resources.dll，以擷取要當地語系化的文字內容。

將 LocBaml.exe 複製到應用程式的 bin\debug 資料夾，這是建立主要應用程式組件的位置。
若要剖析附屬組件檔案，並將輸出儲存成 .csv 檔案，請使用下列命令：

LocBaml.exe /parse HelloApp.resources.dll /out:Hello.csv

注意

如果輸入檔 HelloApp.resources.dll 不是在與 LocBaml.exe 相同的目錄中，請移動其中一個檔案，讓這兩個檔案都在相同的目錄中。

當您執行 LocBaml 來剖析檔案時，輸出中會包含以逗號 (.csv 檔案) 或定位點 (.txt 檔) 分隔的七個欄位。下面顯示針對 HelloApp.resources.dll 所剖析的 .csv 檔案：

已剖析的 .csv 檔案
HelloApp.g.en-US.resources:window1.baml,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;
HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Hello World
HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World

這七個欄位為：

BAML 名稱。有關來源語言附屬組件的 BAML 資源名稱。
資源索引鍵。當地語系化的資源識別碼。
類別。值型別。請參閱當地語系化屬性和註解。
可讀性。當地語系化工具是否能夠讀取該值。請參閱當地語系化屬性和註解。
可修改性. 當地語系化工具是否能夠修改該值。請參閱當地語系化屬性和註解。
註解。該值的其他說明，有助於判斷某值當地語系化的方式。請參閱當地語系化屬性和註解。
值。要轉譯成所需文化特性的文字值。

下表顯示這些欄位如何對應至 .csv 檔案的分隔值：

BAML 名稱	資源索引鍵	類別	可讀性	可修改性	值
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	忽略	FALSE	FALSE	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	無	TRUE	TRUE	Hello World
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	無	TRUE	TRUE	Goodbye World

請注意，[註解] 欄位的所有值不含任何值；如果欄位沒有值，則為空白。另請注意，無法讀取或修改第一個資料列中的項目，且其 [分類] 值為 "Ignore"，這一切都表示該值無法當地語系化。

為了幫助在已剖析的檔案中探索可當地語系化的項目，特別是在大型檔案中，您可以依 [分類]、[可讀性] 和 [可修改性] 來將項目排序或篩選。例如，您可以篩選出無法讀取及無法修改的值。

翻譯可當地語系化的內容

使用您可以用來轉譯擷取內容的任何工具。有一個很好的方法可執行此作業，就是將資源寫入至 .csv 檔案，然後在 Microsoft Excel 中檢視，對最後一個資料行 (值) 進行翻譯變更。

使用 LocBaml 產生新的 .resources.dll 檔案

藉由使用 LocBaml 來剖析 HelloApp.resources.dll 而識別的內容已轉譯，且必須合併回原始應用程式。使用 generate 或 -g 選項產生新的 .resources.dll 檔案。

使用下列語法來產生新的 HelloApp.resources.dll 檔案。將文化特性標示為 en-US (/cul:en-US)。

LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US

注意

如果輸入檔 Hello.csv 不是在與可執行檔 LocBaml.exe 相同的目錄中，請移動其中一個檔案，讓這兩個檔案都在相同的目錄中。
將 C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll 目錄中舊的 HelloApp.resources.dll 檔案取代為新建立的 HelloApp.resources.dll 檔案。
"Hello World" 和 "Goodbye World" 現在應該已在您的應用程式中轉譯。
若要轉譯為不同的文化特性，請使用您想要轉譯之語言的文化特性。下列範例示範如何轉譯成加拿大法文：

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
在與主應用程式組件相同的組件中，建立新的特定文化特性資料夾，以存放新的附屬組件。針對加拿大法文，資料夾會是 fr-CA。
將所產生的附屬組件複製到新的資料夾。

若要測試新的附屬組件，您需要變更您的應用程式用來執行的文化特性。您可以使用下列其中一種作法：

變更作業系統的區域設定。

在您的應用程式中，將下列程式碼加入 App.xaml.cs：

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="SDKSample.App"
    x:Uid="Application_1"
    StartupUri="Window1.xaml">
</Application>

using System.Windows;
using System.Globalization;
using System.Threading;

namespace SDKSample
{
    public partial class App : Application
    {
        public App()
        {
            // Change culture under which this application runs
            CultureInfo ci = new CultureInfo("fr-CA");
            Thread.CurrentThread.CurrentCulture = ci;
            Thread.CurrentThread.CurrentUICulture = ci;
        }
    }
}


Imports System.Windows
Imports System.Globalization
Imports System.Threading

Namespace SDKSample
    Partial Public Class App
        Inherits Application
        Public Sub New()
            ' Change culture under which this application runs
            Dim ci As New CultureInfo("fr-CA")
            Thread.CurrentThread.CurrentCulture = ci
            Thread.CurrentThread.CurrentUICulture = ci
        End Sub
    End Class
End Namespace

使用 LocBaml 的提示

用來定義自訂控制項的所有相依組件，都必須複製到 LocBaml 的本機目錄中，或安裝至 GAC 中。這是必要的，因為當地語系化 API 在讀取二進位 XAML (BAML) 時，必須能夠存取相依組件。
如果主要組件已簽署，所產生的資源 DLL 也必須簽署，才能將其載入。
當地語系化資源 DLL 的版本必須與主要組件同步處理。

共用方式為