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

Статья
12/19/2024

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

Заметка

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

Обзор

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

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

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

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

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

msbuild -t:updateuid helloapp.csproj

Чтобы убедиться, что у вас нет отсутствующих или дублирующихся Uids, выполните 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` {культура]	Локализация выходных сборок.
`translation` или `-trans` {translation.csv]	Переведенный или локализованный файл.
`asmpath` или `-asmpath` {каталогфайлов]	Если код 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,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,,Прощай, мир

Семь полей:

ИМЯ BAML. Имя ресурса BAML в отношении сателлитной сборки исходного языка.
ключ ресурса. Локализованный идентификатор ресурса.
категории. Тип значения. См.: атрибуты локализации и комментарии .
Удобочитаемость. Может ли значение считываться локалиизатором. См. Атрибуты локализации и комментарии.
изменяемость. Можно ли изменить значение локалиизатором. См. Атрибуты локализации и комментарии.
Примечания. Дополнительное описание значения, помогающее определить локализацию значения. См. атрибуты локализации и комментарии.
значение. Текстовое значение для перевода на целевую культуру.

В следующей таблице показано, как эти поля сопоставляются со значениями, разделёнными разделителями, файла .csv.

Имя BAML	Ключ ресурса	Категория	Удобочитаемость	Модификаторность	Ценность
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Игнорировать	НЕВЕРНО	ЛОЖНЫЙ	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	Нет	ПРАВДА	ИСТИНА	Всем привет
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Нет	ИСТИНА	ВЕРНО	Прощай, мир

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

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

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

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

Создание нового файла .resources.dll с помощью LocBaml

Содержимое, которое было идентифицировано с помощью синтаксического анализа 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 или установлены в GAC. Это необходимо, так как API локализации должен иметь доступ к зависимым сборкам при чтении двоичного XAML (BAML).
Если основная сборка подписана, то созданная библиотека ресурсов DLL также должна быть подписана, чтобы загрузиться.
Версия локализованной библиотеки DLL ресурсов должна быть синхронизирована с основной сборкой.

См. также

глобализация для WPF
Используйте обзор автоматической разметки

Поделиться через