如何:对应用程序进行本地化How to: Localize an Application

本教程介绍如何通过使用 LocBaml 工具创建本地化应用程序。This tutorial explains how to create a localized application by using the LocBaml tool.

备注

LocBaml 工具不是可直接用于生产的应用程序。The LocBaml tool is not a production-ready application. 它表示为一个示例,该示例使用某些本地化 API 并演示编写一个本地化工具的方法。It is presented as a sample that uses some of the localization APIs and illustrates how you might write a localization tool.

概述Overview

本讨论提供逐步实现本地化应用程序的方法。This discussion gives you a step-by-step approach to localizing an application. 首先,你要准备应用程序,以便可以提取将被翻译的文本。First, you will prepare your application so that the text that will be translated can be extracted. 相关文本翻译后,你要将翻译的文本合并到原始应用程序的新副本中。After the text is translated, you will merge the translated text into a new copy of the original application.

要求Requirements

在此讨论过程中,你将使用 Microsoft 生成引擎(MSBuild),这是从命令行运行的编译器。Over the course of this discussion, you will use Microsoft build engine (MSBuild), which is a compiler that runs from the command line.

此外,还会指导你使用项目文件。Also, you will be instructed to use a project file. 有关如何使用 MSBuild 和项目文件的说明,请参阅生成和部署For instructions on how to use MSBuild and project files, see Build and Deploy.

在此讨论中的所有示例都使用 zh-CN(中文-中国)作为区域设置。All the examples in this discussion use en-US (English-US) as the culture. 这使你能够而无需安装另一种语言就能完成这些示例的步骤。This enables you to work through the steps of the examples without installing a different language.

创建一个简单的应用程序Create a Sample Application

在此步骤中,你将准备要用于本地化的应用程序。In this step, you will prepare your application for localization. Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) 示例提供了 HelloApp 示例,将用于本讨论中的代码示例。In the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) samples, a HelloApp sample is supplied that will be used for the code examples in this discussion. 如果要使用此示例,请从LocBaml 工具示例下载 可扩展应用程序标记语言 (XAML)Extensible Application Markup Language (XAML) 文件。If you would like to use this sample, download the 可扩展应用程序标记语言 (XAML)Extensible Application Markup Language (XAML) files from the LocBaml Tool Sample.

  1. 将应用程序开发到想要开始进行本地化的位置。Develop your application to the point where you want to start localization.

  2. 在项目文件中指定开发语言,以便 MSBuild 生成主程序集和附属程序集(扩展名为 .resources 的文件),以包含非特定语言资源。Specify the development language in the project file so that MSBuild generates a main assembly and a satellite assembly (a file with the .resources.dll extension) to contain the neutral language resources. HelloApp 示例中的项目文件是 HelloApp.csproj。The project file in the HelloApp sample is HelloApp.csproj. 在该文件中,你将找到标识如下的开发语言:In that file, you will find the development language identified as follows:

    <UICulture>en-US</UICulture>

  3. 将 Uid 添加到你的 XAMLXAML 文件。Add Uids to your XAMLXAML files. Uid 用于跟踪对文件的更改并标识必须翻译的项。Uids are used to keep track of changes to files and to identify items that must be translated. 若要将 Uid 添加到文件,请在项目文件上运行updateuidTo add Uids to your files, run updateuid on your project file:

    msbuild-t:updateuid helloapp.resources.dllmsbuild -t:updateuid helloapp.csproj

    若要验证是否没有缺少或重复的 Uid,请运行checkuidTo verify that you have no missing or duplicate Uids, run checkuid:

    msbuild-t:checkuid helloapp.resources.dllmsbuild -t:checkuid helloapp.csproj

    运行updateuid之后,你的文件应包含 uid。After running updateuid, your files should contain Uids. 例如,在 HelloApp 的 Pane1.xaml 文件中,你应能找到下列内容:For example, in the Pane1.xaml file of HelloApp, you should find the following:

    <StackPanel x:Uid="StackPanel_1">

    <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>

    <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>

    </StackPanel>

创建非特定语言资源附属程序集Create the Neutral Language Resources Satellite Assembly

将应用程序配置为生成非特定语言资源附属程序集后,则可生成应用程序。After the application is configured to generate a neutral language resources satellite assembly, you build the application. 这会生成主应用程序程序集,以及 LocBaml 本地化所需的非特定语言资源附属程序集。This generates the main application assembly, as well as the neutral language resources satellite assembly that is required by LocBaml for localization. 若要生成应用程序,请执行以下操作:To build the application:

  1. 编译 Helloapp.resources.dll 以创建动态链接库(DLL):Compile HelloApp to create a dynamic-link library (DLL):

    msbuild helloapp.csprojmsbuild helloapp.csproj

  2. 新创建的主应用程序程序集 HelloApp.exe 创建在下列文件夹中:The newly created main application assembly, HelloApp.exe, is created in the following folder:

    C:\HelloApp\Bin\Debug\

  3. 新创建的非特定语言资源附属程序集 HelloApp.resources.dll 创建在下列文件夹中:The newly created neutral language resources satellite assembly, HelloApp.resources.dll, is created in the following folder:

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

生成 LocBaml 工具Build the LocBaml Tool

  1. 生成 LocBaml 所需的所有文件都位于 WPFWPF 示例中。All the files necessary to build LocBaml are located in the WPFWPF samples. 从C# LocBaml 工具示例下载文件。Download the C# files from the LocBaml Tool Sample.

  2. 从命令行运行项目文件 (locbaml.csproj) 来生成该工具:From the command line, run the project file (locbaml.csproj) to build the tool:

    msbuild locbaml.csprojmsbuild locbaml.csproj

  3. 转到 Bin\Release 目录以查找新创建的可执行文件 (locbaml.exe)。Go to the Bin\Release directory to find the newly created executable file (locbaml.exe). 示例:C:\LocBaml\Bin\Release\locbaml.exe。Example:C:\LocBaml\Bin\Release\locbaml.exe.

  4. 运行 LocBaml 时可指定下列选项:The options that you can specify when you run LocBaml are as follows:

    • parse-p: 分析 BAML、资源或 DLL 文件以生成 .csv 或 .txt 文件。parse or -p: Parses Baml, resources, or DLL files to generate a .csv or .txt file.

    • 生成-g: 通过使用已转换的文件生成本地化的二进制文件。generate or -g: Generates a localized binary file by using a translated file.

    • out-o {filedirectory] 输出文件名。out or -o {filedirectory] : Output file name.

    • culture-cul {culture] 输出程序集的区域设置。culture or -cul {culture] : Locale of output assemblies.

    • 转换或传输 {转换文件] 翻译或本地化文件。translation or -trans {translation.csv] : Translated or localized file.

    • asmpath-asmpath: {filedirectory] 如果 XAMLXAML 代码包含自定义控件,则必须将asmpath提供给自定义控件程序集。asmpath or -asmpath: {filedirectory] : If your XAMLXAML code contains custom controls, you must supply the asmpath to the custom control assembly.

    • nologo: 显示没有徽标或版权信息。nologo: Displays no logo or copyright information.

    • verbose: 显示详细模式信息。verbose: Displays verbose mode information.

    备注

    如果在运行该工具时需要选项列表,请键入LocBaml ,然后按 enter。If you need a list of the options when you are running the tool, type LocBaml.exe and press ENTER.

使用 LocBaml 分析文件Use LocBaml to Parse a File

由于已创建 LocBaml 工具,就可使用它来分析 HelloApp.resources.dll,从而提取将进行本地化的文本内容。Now that you have created the LocBaml tool, you are ready to use it to parse HelloApp.resources.dll to extract the text content that will be localized.

  1. 将 LocBaml.exe 复制到应用程序的 bin\debug 文件夹,这也是创建主应用程序程序集的位置。Copy LocBaml.exe to your application's bin\debug folder, where the main application assembly was created.

  2. 若要分析附属程序集文件并将输出存储为 .csv 文件,请使用下列命令:To parse the satellite assembly file and store the output as a .csv file, use the following command:

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

    备注

    如果输入文件 HelloApp.resources.dll 不在 LocBaml.exe 所在的同一目录中,请移动其中一个文件以使两个文件都位于同一目录中。If the input file, HelloApp.resources.dll, is not in the same directory as LocBaml.exe move one of the files so that both files are in the same directory.

  3. 当运行 LocBaml 来分析文件时,输出包含由逗号(.csv 文件)或制表符(.txt 文件)分隔的七个字段。When you run LocBaml to parse files, the output consists of seven fields delimited by commas (.csv files) or tabs (.txt files). 下面显示了 HelloApp.resources.dll 的已分析的 .csv 文件:The following shows the parsed .csv file for the HelloApp.resources.dll:

    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,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 WorldHelloApp.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 WorldHelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World

    这七个字段是:The seven fields are:

    1. BAML 名称BAML Name. 与源语言附属程序集相关的 BAML 资源的名称。The name of the BAML resource with respect to the source language satellite assembly.

    2. 资源键Resource Key. 本地化的资源标识符。The localized resource identifier.

    3. CategoryCategory. 值类型。The value type. 请参阅本地化特性和注释See Localization Attributes and Comments.

    4. ReadabilityReadability. 值是否可以由本地化人员读取。Whether the value can be read by a localizer. 请参阅本地化特性和注释See Localization Attributes and Comments.

    5. ModifiabilityModifiability. 值是否可以由本地化人员修改。Whether the value can be modified by a localizer. 请参阅本地化特性和注释See Localization Attributes and Comments.

    6. 注释Comments. 值的附加说明,用于确定值被本地化的方式。Additional description of the value to help determine how a value is localized. 请参阅本地化特性和注释See Localization Attributes and Comments.

    7. Value. 要翻译为所需区域性设置的文本值。The text value to translate to the desired culture.

    下表显示了这些字段映射到 .csv 文件的分隔值的方式:The following table shows how these fields map to the delimited values of the .csv file:

    BAML 名称BAML name 资源键Resource key 类别Category 可读性Readability 可修改性Modifiability 注释Comments Value
    HelloApp.g.en-US.resources:window1.bamlHelloApp.g.en-US.resources:window1.baml Stack1:System.Windows.Controls.StackPanel.$ContentStack1:System.Windows.Controls.StackPanel.$Content 忽略Ignore FALSEFALSE FALSEFALSE #Text1;#Text2#Text1;#Text2
    HelloApp.g.en-US.resources:window1.bamlHelloApp.g.en-US.resources:window1.baml Text1:System.Windows.Controls.TextBlock.$ContentText1:System.Windows.Controls.TextBlock.$Content None TRUETRUE TRUETRUE Hello WorldHello World
    HelloApp.g.en-US.resources:window1.bamlHelloApp.g.en-US.resources:window1.baml Text2:System.Windows.Controls.TextBlock.$ContentText2:System.Windows.Controls.TextBlock.$Content None TRUETRUE TRUETRUE Goodbye WorldGoodbye World

    请注意,注释字段的所有值不包含任何值;如果字段没有值,则为空。Notice that all the values for the Comments field contain no values; if a field doesn't have a value, it is empty. 另请注意,第一行中的项既不可读也不可修改,并且具有 "Ignore" 作为其类别值,所有这些都指示该值不可本地化。Also notice that the item in the first row is neither readable nor modifiable, and has "Ignore" as its Category value, all of which indicates that the value is not localizable.

  4. 为了便于发现已分析文件中的可本地化项(特别是在大型文件中),可以按类别可读性和可修改性对项进行排序或筛选。To facilitate discovery of localizable items in parsed files, particularly in large files, you can sort or filter the items by Category, Readability, and Modifiability. 例如,你可以筛选出不可读且不可修改的值。For example, you can filter out unreadable and unmodifiable values.

翻译可本地化的内容Translate the Localizable Content

使用任何你可用的工具翻译提取的内容。Use any tool that you have available to translate the extracted content. 实现此目的的一种好方法是将资源写入 .csv 文件,并在 Microsoft Excel 中查看这些资源,对最后一列(值)进行转换。A good way to do this is to write the resources to a .csv file and view them in Microsoft Excel, making translation changes to the last column (value).

使用 LocBaml 生成新的 .resources.dll 文件Use LocBaml to Generate a New .resources.dll File

通过使用 LocBaml 分析 HelloApp.resources.dll 而标识的内容已被翻译,且必须合并回原始应用程序。The content that was identified by parsing HelloApp.resources.dll with LocBaml has been translated and must be merged back into the original application. 使用 "生成" 或 -g选项生成新的 .resources .dll 文件。Use the generate or -g option to generate a new .resources.dll file.

  1. 使用下列语法来生成新的 HelloApp.resources.dll 文件。Use the following syntax to generate a new HelloApp.resources.dll file. 将区域性标记为 zh-CN (/cul:zh-CN)。Mark the culture as en-US (/cul:en-US).

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

    备注

    如果输入文件 Hello.csv 与可执行文件 LocBaml.exe 不在的同一目录中,请移动其中一个文件以使两个文件都位于同一目录中。If the input file, Hello.csv, is not in the same directory as the executable, LocBaml.exe, move one of the files so that both files are in the same directory.

  2. 使用新创建的 HelloApp.resources.dll 文件替换 C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll 目录中的旧 HelloApp.resources.dll 文件。Replace the old HelloApp.resources.dll file in the C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll directory with your newly created HelloApp.resources.dll file.

  3. 应在你的应用程序中将“Hello World”和“Goodbye World”翻译过来。"Hello World" and "Goodbye World" should now be translated in your application.

  4. 若要翻译到不同的区域性设置,请使用目标语言的区域设置。To translate to a different culture, use the culture of the language that you are translating to. 下列示例演示了如何翻译为加拿大法语:The following example shows how to translate to French-Canadian:

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

  5. 在主应用程序程序集所在的程序集,创建一个新的特定于区域性的文件夹,以容纳新的附属程序集。In the same assembly as the main application assembly, create a new culture-specific folder to house the new satellite assembly. 对于加拿大法语,该文件夹将为 fr-CA。For French-Canadian, the folder would be fr-CA.

  6. 将生成的附属程序集复制到新建文件夹。Copy the generated satellite assembly to the new folder.

  7. 若要测试新的附属程序集,你需要更改应用程序将在其下运行的区域性设置。To test the new satellite assembly, you need to change the culture under which your application will run. 可以通过两种方法执行此操作:You can do this in one of two ways:

    • 更改操作系统的区域设置("启动 | " "控制面板" " | 区域和语言选项")。Change your operating system's regional settings (Start | Control Panel | Regional and Language Options).

    • 在你的应用程序中,将下列代码添加到 App.xaml.cs 中:In your application, add the following code to 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 的一些提示Some Tips for Using LocBaml

  • 所有定义自定义控件的依赖程序集必须复制到 LocBaml 的本地目录,或安装到 GAC。All dependent assemblies that define custom controls must be copied into the local directory of LocBaml or installed into the GAC. 这是必需的,因为本地化 API 在读取二进制 XAML (BAML)时必须具有对依赖程序集的访问权限。This is necessary because the localization API must have access to the dependent assemblies when it reads the binary XAML (BAML).

  • 如果主程序集已签名,则生成的资源 DLL 也必须签名以进行加载。If the main assembly is signed, the generated resource DLL must also be signed in order for it to be loaded.

  • 本地化的资源 DLL 的版本需与主程序集进行同步。The version of the localized resource DLL needs to be synchronized with the main assembly.

后续步骤What's Next

现在,你应该对如何使用 LocBaml 工具有了一个基本的了解。You should now have a basic understanding of how to use the LocBaml tool. 你应该能够制作包含 Uid 的文件。You should be able to make a file that contains Uids. 通过使用 LocBaml 工具,你应该能够分析文件以提取可本地化的内容,并且在内容翻译后,你应该能够生成一个合并已翻译内容的 resources.dll 文件。By using the LocBaml tool, you should be able to parse a file to extract the localizable content, and after the content is translated, you should be able to generate a .resources.dll file that merges the translated content. 本主题不包括每个可能的细节,但现在你已经掌握了使用 LocBaml 对应用程序进行本地化的必要知识。This topic does not include every possible detail, but you now have the knowledge necessary to use LocBaml for localizing your applications.

另请参阅See also