如何：本地化应用程序

项目
01/30/2025

本教程介绍如何使用 LocBaml 工具创建本地化的应用程序。

说明

LocBaml 工具不是适用于生产环境的应用程序。它以示例形式呈现，该示例使用一些本地化 API，并说明了如何编写本地化工具。

概述

本文提供本地化应用程序的分步方法。首先，准备您的应用程序，以便让需要翻译的文本可以被提取出来。翻译文本后，将翻译后的文本合并到原始应用程序的新副本中。

创建示例应用程序

在此步骤中，你将为本地化准备应用。在 Windows Presentation Foundation （WPF）示例中，提供了一个 HelloApp 示例，该示例将用于本讨论中的代码示例。若要使用此示例，请从 LocBaml 工具示例下载可扩展应用程序标记语言（XAML）文件。

将应用程序开发到要开始本地化的位置。
在项目文件中指定开发语言，以便 MSBuild 生成主程序集和附属程序集（具有 .resources.dll 扩展名的文件）以包含中性语言资源。 HelloApp 示例中的项目文件是 HelloApp.csproj。在该文件中，你将找到标识如下的开发语言：

<UICulture>en-US</UICulture>
将 UIDs 添加到 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` {文件目录]	输出文件名。
`culture` 或 `-cul` {culture]	输出程序集的区域设置。
`translation` 或 `-trans` {translation.csv]	已翻译或本地化的文件。
`asmpath` 或 `-asmpath` {文件目录]	如果 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	世界您好
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	没有	true	true	再见世界

请注意，注释字段的所有值不包含任何值;如果字段没有值，则为空。另请注意，第一行中的项既不可读也不可修改，并且具有“忽略”作为其 Category 值，所有这些都指示该值不可本地化。

为了便于发现已分析文件中的可本地化项，特别是在大型文件中，可以通过类别、可读性和 可修改性对项进行排序或筛选。例如，可以筛选出不可读和不可修改的值。

翻译可本地化的内容

使用任何可用于翻译提取内容的工具。执行此操作的一个好方法是将资源写入 .csv 文件并在 Excel Microsoft中查看它们，对最后一列（值）进行翻译更改。

使用 LocBaml 生成新的 .resources.dll 文件

通过使用 LocBaml 分析 HelloApp.resources.dll 而标识的内容已被翻译，且必须合并回原始应用程序。使用 generate 或 -g 选项生成新的 .resources.dll 文件。

使用以下语法生成新的 HelloApp.resources.dll 文件。将区域性标记为 zh-CN (/cul:zh-CN)。

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”和“再见世界”现在应在应用程序中翻译。
若要翻译到不同的区域性设置，请使用目标语言的区域设置。下列示例演示了如何翻译为加拿大法语：

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 的版本需要与主程序集同步。

通过