Как локализовать приложение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 article gives you a step-by-step approach to localizing an application. Сначала необходимо подготовить приложение, чтобы можно было извлечь текст, который будет преобразован.First, you prepare your application so that the text that will be translated can be extracted. После перевода текста выполняется слияние переведенного текста в новую копию исходного приложения.After the text is translated, you merge the translated text into a new copy of the original application.

Создание примера приложенияCreate a sample application

На этом шаге вы подготовите приложение к локализации.In this step, you prepare your app for localization. В примерах Windows Presentation Foundation (WPF) предоставляется образец HelloApp, который будет использоваться для примеров кода в этом обсуждении.In the Windows Presentation Foundation (WPF) samples, a HelloApp sample is supplied that will be used for the code examples in this discussion. Если вы хотите использовать этот пример, Скачайте файлы XAML (XAML) из примера средства LocBaml.If you would like to use this sample, download the 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. 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. Добавьте идентификаторы UID в файлы XAML.Add Uids to your XAML 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 -t:updateuid helloapp.csproj

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

    msbuild -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's required by LocBaml for localization.

Чтобы создать приложение:To build the application:

  1. Скомпилируйте HelloApp, чтобы создать библиотеку динамической компоновки (DLL):Compile HelloApp to create a dynamic-link library (DLL):

    msbuild 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, находятся в примерах WPF.All the files necessary to build LocBaml are located in the WPF 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.csproj

  3. Перейдите в каталог Bin\Release , чтобы найти только что созданный исполняемый файл (LocBaml. exe).Go to the Bin\Release directory to find the newly created executable file (locbaml.exe). Пример: к:\локбамл\бин\релеасе\локбамл.ЕКСЕExample: C:\LocBaml\Bin\Release\locbaml.exe

  4. При запуске LocBaml можно указать следующие параметры.The options that you can specify when you run LocBaml are as follows.

    ПараметрOption ОписаниеDescription
    parse или -pparse or -p Анализирует файлы BAML, Resources или DLL для создания файла CSV или txt.Parses Baml, resources, or DLL files to generate a .csv or .txt file.
    generate или -ggenerate 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или -trans {Translation. csv]translation or -trans {translation.csv] Переведенный или локализованный файл.Translated or localized file.
    asmpathили -asmpath {филедиректори]asmpath or -asmpath {filedirectory] Если код XAML содержит пользовательские элементы управления, необходимо предоставить его asmpath сборке пользовательского элемента управления.If your XAML code contains custom controls, you must supply the asmpath to the custom control assembly.
    nologo запрещает отображение логотипа или сведений об авторских правах.Displays no logo or copyright information.
    verbose отображает сведения режима подробного протоколирования.Displays verbose mode information.

    Примечание

    Если при запуске средства требуется список параметров, введите LocBaml.exe и нажмите клавишу Ввод.If you need a list of the options when you are running the tool, enter LocBaml.exe and then 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.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:

    В следующей таблице показывается, как эти поля соответствуют разделенным значениям 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 Ложь.FALSE Ложь.FALSE #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-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 в каталоге к:\хеллоапп\бин\дебуг\ен-ус\хеллоапп.ресаурцес.длл на созданный файл 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-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.

    • В своем приложении добавьте в файл 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
      

Советы по использованию LocBamlTips 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.

См. такжеSee also