Практическое руководство. Локализация приложения

Статья
06/02/2023

В этом учебнике рассматривается создание локализованного приложения с помощью средства LocBaml.

Примечание.

Средство LocBaml не является готовым приложением. Оно представлено в качестве примера, в котором используются некоторые API локализации и показывается, как можно написать средство локализации.

Обзор

В этой статье предоставляется поэтапный подход к локализации приложений. Сначала необходимо подготовить приложение так, чтобы можно было извлечь текст, который будет переведен. После перевода текста требуется влить переведенный текст в новую копию исходного приложения.

Создание примера приложения

На этом шаге вы будете выполнять подготовку приложения к локализации. В примерах Windows Presentation Foundation (WPF) предоставляется приложение HelloApp, которое будет использоваться для примеров кода в этом ра(ЦЗА) Если вы хотите использовать этот пример приложения, скачайте файлы XAML со страницы Пример средства LocBaml.

Разработайте свое приложение до точки, в которой хотите начать локализацию.
Укажите язык разработки в файле проекта, чтобы создал основную сборку и вспомогательную сборку (файл с расширением .resources.dll), которая будет содержать ресурсы нейтрального языка. Файл проекта в примере HelloApp — HelloApp.csproj. В этом файле можно найти язык разработки, заданный следующим образом:

<UICulture>en-US</UICulture>
Добавьте ИД пользователей в свои файлы XAML. ИД пользователей используются для отслеживания изменений в файлах и для идентификации элементов, которые должны быть переведены. Чтобы добавить ИД пользователей в файлы, запустите updateuid в вашем файле проекта:

msbuild -t:updateuid helloapp.csproj

Чтобы проверить, имеются ли отсутствующие или дублированные ИД пользователей, запустите checkuid:

msbuild -t:checkuid helloapp.csproj

После выполнения updateuid файлы должны содержать ИД пользователей. Например, в файле Pane1.xaml приложения HelloApp вы должны найти следующее:
```
<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. Скачайте файлы C# со страницы Пример средства LocBaml.
Из командной строки запустите файл проекта (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` {filedirectory]	Имя файла выходных данных.
`culture` или `-cul` {culture]	Языковой стандарт выходных сборок.
`translation` или `-trans` {translation.csv]	Переведенный или локализованный файл.
`asmpath` или `-asmpath` {filedirectory]	Если ваш код XAML содержит пользовательские элементы управления, необходимо предоставить `asmpath` в сборку пользовательского элемента управления.
`nologo`	Отображает никаких сведений о логотипе или авторских правах.
`verbose`	Отображает подробные сведения о режиме.

Примечание.

Если при запуске этого средства вам потребуется список параметров, введите LocBaml.exe и нажмите клавишу ВВОД.

Использование 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-файлы). Ниже показан проанализированный CSV-файл для 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,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;

Это следующие семь полей.

Имя 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	None	TRUE	TRUE	Hello World
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	None	TRUE	TRUE	Goodbye World

Обратите внимание, что все значения для поля Комментарии отсутствуют; если поле не имеет значения, оно пустое. Также обратите внимание, что элемент в первой строке не является ни читаемым, ни изменяемым и его поле Категория имеет значение Ignore. Все это указывает, что это значение не локализуемое.

Чтобы облегчить поиск локализуемых элементов в проанализированных файлах, особенно если они большие, можно сортировать или фильтровать элементы по категории, удобочитаемости и изменяемости. Например можно отфильтровать нечитаемые и неизменяемые значения.

Перевод локализуемого содержимого

Используйте любое доступное средство для перевода извлеченного содержимого. Для этого рекомендуется записать ресурсы в CSV-файл и просматривать их в Microsoft Excel, внося переведенный текст в последний столбец (значение).

Использование LocBaml для создания нового файла .resources.dll

Содержимое, которое было идентифицировано при анализе файла HelloApp.resources.dll с помощью LocBaml, переведено, и его необходимо влить обратно в исходное приложение. Используйте параметр generate или -g, чтобы создать новый файл .resources.dll.

Чтобы создать новый файл HelloApp.resources.dll, используйте следующий синтаксис. Пометьте язык и региональные параметры как en-US (/cul:en-US).

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

Примечание.

Если входной файл Hello.csv не находится в том же каталоге, что и исполняемый файл LocBaml.exe, переместите один из файлов таким образом, чтобы оба файла были в одном каталоге.
Замените старый файл HelloApp.resources.dll в каталоге C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll на новый созданный файл HelloApp.resources.dll.
Теперь в вашем приложении фразы Hello World и Goodbye 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 или установлены в глобальном кэше сборок. Это необходимо потому, что API локализации должен иметь доступ к зависимым сборкам при чтении двоичного файла XAML (BAML).
Если основная сборка имеет подпись, созданная библиотека DLL ресурсов также должна быть подписана для ее загрузки.
Версия библиотеки DLL локализованных ресурсов должна быть синхронизирована с основной сборкой.