Практическое руководство. Локализация приложения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 Build Engine (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.

Во всех примерах в этом разделе в качестве языка и региональных параметров используется en-US (английский (США)).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. Если вы хотите использовать этот пример, Скачайте файлы Язык XAMLExtensible Application Markup Language (XAML) из примера средства LocBaml.If you would like to use this sample, download the Язык XAMLExtensible 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. dll) для хранения нейтральных языковых ресурсов.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. Добавьте ИД пользователей в свои файлы XAMLXAML.Add Uids to your XAMLXAML files. ИД пользователей используются для отслеживания изменений в файлах и для идентификации элементов, которые должны быть переведены.Uids are used to keep track of changes to files and to identify items that must be translated. Чтобы добавить ИД пользователей в файлы, запустите updateuid в файле проекта:To add Uids to your files, run updateuid on your project file:

    MSBuild-т:упдатеуид HelloApp. csprojmsbuild -t:updateuid helloapp.csproj

    Чтобы убедиться в отсутствии отсутствующих или повторяющихся ИД UID, выполните checkuid:To verify that you have no missing or duplicate Uids, run checkuid:

    MSBuild-т:чеккуид HelloApp. csprojmsbuild -t:checkuid helloapp.csproj

    После выполнения updateuidфайлы должны содержать идентификаторы UID.After running updateuid, your files should contain Uids. Например, в файле Pane1.xaml приложения HelloApp вы должны найти следующее: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, чтобы создать библиотеку динамической компоновки (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\

Построение средства LocBamlBuild 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, Resources или DLL для создания файла CSV или txt.parse or -p: Parses Baml, resources, or DLL files to generate a .csv or .txt file.

    • Generate или -g: создает локализованный двоичный файл с помощью переведенного файла.generate or -g: Generates a localized binary file by using a translated file.

    • out или -o {филедиректори] : имя выходного файла.out or -o {filedirectory] : Output file name.

    • culture или -CUL {culture] : языковой стандарт для выходных сборок.culture or -cul {culture] : Locale of output assemblies.

    • Преобразование или -транзакции {Translation. csv] : переведенный или локализованный файл.translation or -trans {translation.csv] : Translated or localized file.

    • asmpath или -asmpath: {филедиректори] : если ваш код 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. exe и нажмите клавишу ВВОД.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). Ниже показан проанализированный CSV-файл для HelloApp.resources.dll: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,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,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;HelloApp.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. Категория.Category. Тип значения.The value type. См. раздел атрибуты и комментарии локализации.See Localization Attributes and Comments.

    4. Удобочитаемость.Readability. Может ли значение быть прочитано средством локализации.Whether the value can be read by a localizer. См. раздел атрибуты и комментарии локализации.See Localization Attributes and Comments.

    5. Изменяемость.Modifiability. Может ли значение изменяться средством локализации.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:

    Имя BAMLBAML 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 Text1:System.Windows.Controls.TextBlock.$ContentText2:System.Windows.Controls.TextBlock.$Content ОтсутствуютNone trueTRUE trueTRUE Goodbye WorldGoodbye World

    Обратите внимание, что все значения поля Comments не содержат значений. Если поле не имеет значения, оно пустое.Notice that all the values for the Comments field contain no values; if a field doesn't have a value, it is empty. Также обратите внимание, что элемент в первой строке не является ни читаемым, ни изменяемым, а параметр Category имеет значение "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.dllUse LocBaml to Generate a New .resources.dll File

Содержимое, которое было идентифицировано при анализе файла HelloApp.resources.dll с помощью LocBaml, переведено, и его необходимо влить обратно в исходное приложение.The content that was identified by parsing HelloApp.resources.dll with LocBaml has been translated and must be merged back into the original application. Используйте параметр Generate или -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. Пометьте язык и региональные параметры как en-US (/cul:en-US).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
    

Советы по использованию LocBamlSome Tips for Using LocBaml

  • Все зависимые сборки, которые определяют пользовательские элементы управления, должны быть скопированы в локальный каталог LocBaml или установлены в глобальном кэше сборок.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. Вы можете создать файл, содержащий ИД пользователей.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