共用方式為

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

  • 發行項

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

注意事項注意事項

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

這個主題包含下列章節。

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

概觀

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

需求

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

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

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

建立範例應用程式

在這個步驟中，您會將應用程式準備好以進行當地語系化。 Windows Presentation Foundation (WPF) 範例附有一個 HelloApp 範例，本課程將使用它做為程式碼範例。 如果您要使用此範例，請從 LocBaml 工具範例 (英文) 下載Extensible Application Markup Language (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 來建立dynamic-link library (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

    Ignore

    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>

      
Imports System.Windows ' Application
Imports System.Globalization ' CultureInfo
Imports System.Threading ' Thread

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

      using System.Windows; // Application
using System.Globalization; // CultureInfo
using System.Threading; // Thread

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

使用 LocBaml 的一些秘訣

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

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

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

下一步

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

請參閱

概念

WPF 的全球化

使用自動配置概觀