HOW TO：將應用程式當地語系化

  • 發行項

更新：2007 年 11 月

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

注意事項：

LocBaml 工具是尚未產品化的應用程式。它做為範例使用，其使用部分已當地語系化的 API 並示範如何撰寫當地語系化工具。

這個主題包含下列章節。

  • 概觀
  • 需求
  • 建立範例應用程式
  • 建立中性語言資源附屬組件
  • 建置 LocBaml 工具
  • 使用 LocBaml 剖析檔案
  • 翻譯可當地語系化的內容
  • 使用 LocBaml 產生新的 .resources.dll 檔案
  • 使用 LocBaml 的一些秘訣
  • 下一步
  • 相關主題

概觀

以下的討論將逐步引導您建立當地語系化版本的應用程式。首先，您將準備好應用程式，以擷取要翻譯的文字。在翻譯文字之後，再將翻譯好的文字合併到原始應用程式的新複本。

需求

在本課程進行期間，您會使用到 Microsoft Build Engine (MSBuild)，這是從命令列執行的編譯器。

此外，您也需要使用專案檔。如需如何使用 MSBuild 和專案檔的說明，請參閱建置和部署 Windows Presentation Foundation 應用程式。

本教學中的所有範例都使用 en-US (英文-美國) 文化特性 (Culture)。這可讓您在不需要安裝其他語言的情況下，逐步完成範例的步驟。

建立範例應用程式

在這個步驟中，您會將應用程式準備好以進行當地語系化。Windows Presentation Foundation (WPF) 範例附有一個 HelloApp 範例，本課程將使用它做為程式碼範例。如果您要使用這個範例，請從 LocBaml 工具範例下載可延伸標記語言 (XAML) 檔案。

  1. 開發應用程式，直到要進行當地語系化的程度為止。

  2. 在專案檔中指定開發語言，以便 MSBuild 產生主要組件和附屬組件 (副檔名為 .resources.dll 的檔案)，來包含中性語言資源。HelloApp 範例中的專案檔是 HelloApp.csproj。在該檔案中，您會發現開發語言的指定會如下所示：

    <UICulture>en-US</UICulture>

  3. 將 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 進行當地語系化所需的中性語言資源附屬組件。若要建置應用程式：

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

    msbuild helloapp.csproj

  2. 這個新建立的主應用程式組件 HelloApp.exe 會放在下列資料夾中：

    C:\HelloApp\Bin\Debug\

  3. 這個新建立的中性語言資源附屬組件 HelloApp.resources.dll 會放在下列資料夾中：

    C:\HelloApp\Bin\Debug\en-US\

建置 LocBaml 工具

  1. 建置 LocBaml 所需的所有檔案都位於 WPF 範例中。請從 LocBaml 工具範例範例下載 C# 檔案。

  2. 使用命令列來執行專案檔 (locbaml.csproj) 以建置工具：

    msbuild locbaml.csproj

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

  4. 執行 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，以擷取將進行當地語系化的文字內容。

  1. 將 LocBaml.exe 複製到應用程式的 bin\debug 資料夾，也就是建立主應用程式組件的位置。

  2. 若要剖析附屬組件檔並將輸出儲存成 .csv 檔案，請使用下列命令：

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

    注意事項：

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

  3. 當您執行 LocBaml 剖析檔案時，輸出的內容會有七個欄位，並以逗號 (.csv 檔案) 或定位點 (.txt 檔案) 分隔。下面顯示 HelloApp.resources.dll 剖析作業中產生的 .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

    這七個欄位分別為：

    1. BAML 名稱。與來源語言附屬組件相關的 BAML 資源名稱。

    2. 資源索引鍵。已當地語系化的資源識別項。

    3. 分類：值型別。請參閱當地語系化屬性和註解。

    4. 可否讀取：當地語系化工具是否可讀取值。請參閱當地語系化屬性和註解。

    5. 可否修改：當地語系化工具是否可修改值。請參閱當地語系化屬性和註解。

    6. 註解。值的詳細描述，以協助判斷如何當地語系化該值。請參閱當地語系化屬性和註解。

    7. 值。要翻譯成所需文化特性的文字值。

    下表顯示這些欄位如何對應到 .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

    請注意，所有值在 [註解] 欄位中都不具有值；如果欄位沒有值，就是空白的。另外也請注意，第一列中的項目無法讀取也無法修改，其 [分類] 的值為「忽略」，這些都表示值是無法當地語系化的。

  4. 為更快在剖析好的檔案中找到可當地語系化的項目，特別是在大型檔案中，您可以依 [分類]、[可否讀取] 和 [可否修改] 排序或篩選項目。例如，您可以篩選掉無法讀取和無法修改的值。

翻譯可當地語系化的內容

請使用您所擁有的任何工具來翻譯所擷取的內容。有個好方法是將資源寫入 .csv 檔案並在 Microsoft Excel 中檢視這些資源，然後在最後一欄 (值) 進行翻譯變更作業。

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

翻譯使用 LocBaml 剖析 HelloApp.resources.dll 所識別的內容這時已完成翻譯，接下來就必須合併回原始應用程式。請使用 generate 或 -g 選項產生新的 .resources.dll 檔案。

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

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

    注意事項：

    如果輸入檔案 Hello.csv 與可執行檔 LocBaml.exe 不是位於相同目錄中，請移動其中一個檔案，讓兩個檔案位於相同的目錄中。

  2. 將 C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll 目錄中舊有的 HelloApp.resources.dll 檔案取代為新建立的 HelloApp.resources.dll 檔案。

  3. "Hello World" 和 "Goodbye World" 的譯文這時應該已經出現在應用程式中。

  4. 若要翻譯成其他文化特性，請使用要翻譯的目標語言的文化特性。下列範例顯示如何翻譯成加拿大法文：

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

  5. 在與主應用程式組件相同的組件中，建立新的文化特性專用資料夾，以存放新的附屬組件。加拿大法文的資料夾就是 fr-CA。

  6. 將產生的附屬組件複製到新的資料夾。

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

    • 變更作業系統的地區設定 ([開始] | [控制台] | [區域及語言選項])。

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

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

使用 LocBaml 的一些秘訣

  • 所有定義自訂控制項的相依組件都必須複製到 LocBaml 的本機目錄或安裝到 GAC。必須這麼做的原因，是因為當地語系化的 API 讀取二進位 XAML (BAML) 時，必須能存取相依組件。

  • 如果主要組件已簽署，那麼產生的資源 DLL 也必須簽署才能載入。

  • 當地語系化的資源 DLL 版本必須與主要組件一致。

下一步

您現在應該對如何使用 LocBaml 工具有基本的認識。您應能夠建立包含 Uid 的檔案。藉由使用 LocBaml 工具，您應能夠剖析檔案來擷取可當地語系化的內容，而且在翻譯內容之後，也應能夠產生 .resources.dll 檔案以合併翻譯好的內容。本課程雖無法涵蓋每項細節，但您現在應已具備必要的知識，能夠使用 LocBaml 當地語系化應用程式。

請參閱

概念

全球化 Windows Presentation Foundation

使用自動配置概觀