Vorgehensweise: Lokalisieren einer Anwendung

Artikel
05/04/2023

In diesem Lernprogramm wird erläutert, wie eine lokalisierte Anwendung mit dem LocBaml-Tool erstellt wird.

Hinweis

Das LocBaml-Tool ist keine einsatzfertige Anwendung. Es wird als Beispiel präsentiert, das einen Teil der Lokalisierungs-APIs verwendet und veranschaulicht, wie Sie ein Lokalisierungstool schreiben können.

Übersicht

Dieser Artikel bietet einen schrittweisen Ansatz zum Lokalisieren einer Anwendung. Zuerst bereiten Sie Ihre Anwendung so vor, dass der zu übersetzende Text extrahiert werden kann. Nachdem der Text übersetzt wurde, führen Sie den übersetzten Text mit einer neuen Kopie der ursprünglichen Anwendung zusammen.

Erstellen einer Beispielanwendung

In diesem Schritt bereiten Sie Ihre Anwendung für die Lokalisierung vor. In den Windows Presentation Foundation- (WPF)-Beispielen wird die Beispielanwendung HelloApp bereitgestellt, die für die Codebeispiele in dieser Diskussion verwendet wird. Wenn Sie dieses Beispiel verwenden möchten, laden Sie die XAML-Dateien (Extensible Application Markup Language) vom LocBaml Tool Sample herunter.

Entwickeln Sie Ihre Anwendung bis zu dem Punkt, an dem Sie die Lokalisierung starten möchten.
Geben Sie die Entwicklungssprache in der Projektdatei so an, dass MSBuild eine Hauptassembly und eine Satellitenassembly (eine Datei mit der Erweiterung ".resources.dll") generiert, die die neutralen Sprachressourcen enthält. Die Projektdatei im HelloApp-Beispiel ist "HelloApp.csproj". In dieser Datei finden Sie die Entwicklungssprache wie folgt gekennzeichnet:

<UICulture>en-US</UICulture>
Fügen Sie den XAML-Dateien UIDs hinzu. UIDs werden verwendet, um Änderungen an Dateien nachzuverfolgen und die Elemente zu identifizieren, die übersetzt werden müssen. Um den Dateien UIDs hinzuzufügen, führen Sie updateuid für die Projektdatei aus:

msbuild -t:updateuid helloapp.csproj

Um sicherzustellen, dass keine UIDs fehlen bzw. doppelt vorhanden sind, führen Sie checkuid aus:

msbuild -t:checkuid helloapp.csproj

Nach dem Ausführen von updateuid sollten Ihre Dateien UIDs enthalten. Beispielsweise sollten Sie in der Datei Pane1.xaml von HelloApp Folgendes finden:
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

Erstellen der Satellitenassembly mit den neutralen Sprachressourcen

Nachdem die Anwendung so konfiguriert ist, dass eine Satellitenassembly mit den neutralen Sprachressourcen generiert wird, erstellen Sie die Anwendung. Auf diese Weise werden die Hauptassembly der Anwendung und die Satellitenassembly mit den neutralen Sprachressourcen generiert, die LocBaml für die Lokalisierung benötigt.

So erstellen Sie die Anwendung:

Kompilieren Sie HelloApp zum Erstellen einer dynamischen Linkbibliothek (DLL):

msbuild helloapp.csproj
Die neu erstellte Hauptanwendungsassembly, "HelloApp.exe", wird im folgenden Ordner erstellt: C:\HelloApp\Bin\Debug
Die neu erstellte Satellitenassembly mit den neutralen Sprachressourcen, "HelloApp.resources.dll", wird im folgenden Ordner erstellt: C:\HelloApp\Bin\Debug\en-US

Erstellen des LocBaml-Tools

Alle für das Erstellen von LocBaml notwendigen Dateien befinden sich in den WPF-Beispielen. Laden Sie der C#-Dateien aus dem Beispiel zum LocBaml-Tool herunter.
Führen Sie über die Befehlszeile die Projektdatei (locbaml.csproj) aus, um das Tool zu erstellen:

msbuild locbaml.csproj
Wechseln Sie zum Verzeichnis Bin\Release, um die neu erstellte ausführbare Datei (locbaml.exe) zu finden. Beispiel: C:\LocBaml\Bin\Release\locbaml.exe

Für ein Ausführen von LocBaml können Sie folgende Optionen angeben:

Option	Beschreibung
`parse` oder `-p`	Analysiert Baml-, Ressourcen- oder -Dateien, um eine CSV- oder TXT-Datei zu generieren.
`generate` oder `-g`	oder generiert eine lokalisierte Binärdatei, indem eine übersetzte Datei verwendet wird.
`out` oder `-o` {filedirectory]	Name der Ausgabedatei.
`culture` oder `-cul` {Kultur]	Gebietsschema von Ausgabeassemblys.
`translation` oder `-trans` {translation.csv]	Übersetzte oder lokalisierte Datei.
`asmpath` oder `-asmpath` {filedirectory]	Wenn Ihr XAML-Code benutzerdefinierte Steuerelemente enthält, müssen Sie den `asmpath` für die benutzerdefinierte Steuerelementassembly angeben.
`nologo`	Bewirkt, dass weder ein Logo noch Copyrightinformationen angezeigt werden.
`verbose`	Bewirkt, dass Informationen im ausführlichen Modus angezeigt werden.

Hinweis

Wenn Sie eine Liste der Optionen benötigen, während Sie das Tool ausführen, geben Sie LocBaml.exe ein und drücken Sie dann Enter.

Verwenden von LocBaml zum Analysieren einer Datei

Nachdem Sie das LocBaml-Tool erstellt haben, können Sie es verwenden, um "HelloApp.resources.dll" zu analysieren, um den Textinhalt zu extrahieren, der lokalisiert wird.

Kopieren Sie "LocBaml.exe" in den "bin\debug"-Ordner Ihrer Anwendung, in dem die Hauptanwendungsassembly erstellt wurde.
Um die Satellitenassemblydatei zu analysieren und die Ausgabe als CSV-Datei zu speichern, verwenden Sie den folgenden Befehl ein:

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

Hinweis

Wenn sich die Eingabedatei "HelloApp.resources.dll" nicht im selben Ordner wie "LocBaml.exe" befindet, verschieben Sie eine der Dateien, damit sich beide Dateien im selben Verzeichnis befinden.

Wenn Sie LocBaml ausführen, um Dateien zu analysieren, besteht die Ausgabe aus sieben Feldern, die jeweils durch Kommas (CSV-Dateien) oder Tabulatoren (TXT-Dateien) getrennt sind. Nachstehend ist die bei der Analyse erstellte CSV-Datei für "HelloApp.Resources.dll" gezeigt:

Analysierte .csv Datei
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,,Goodbye World

Die sieben Felder sind:

BAML-Name. Der Name der BAML-Ressource bezogen auf die Satellitenassembly für die Ausgangssprache.
Ressourcenschlüssel. Der lokalisierte Ressourcenbezeichner.
Kategorie Der Werttyp. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Lesbarkeit. Gibt an, ob der Wert von einem Lokalisierungstool gelesen werden kann. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Änderbarkeit. Gibt an, ob der Wert von einem Lokalisierungstool geändert werden kann. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Kommentare. Zusätzliche Beschreibung des Werts, um zu ermitteln, wie ein Wert lokalisiert wird. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Wert. Der Textwert, der in die gewünschte Sprache übersetzt werden soll.

Die folgende Tabelle zeigt, wie diese Felder den durch Trennzeichen getrennten Werten der CSV-Datei zugeordnet sind:

BAML-Name	Ressourcenschlüssel	Kategorie	Lesbarkeit	Änderbarkeit	Wert
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Ignorieren	FALSE	FALSE	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	Keine	TRUE	TRUE	Hello World
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Keine	TRUE	TRUE	Goodbye World

Beachten Sie, dass alle Werte für das Feld Kommentare keine Werte enthalten. Hat ein Feld keinen Wert, ist es leer. Beachten Sie auch, dass das Element in der ersten Zeile weder lesbar noch änderbar ist und „Ignorieren“ als Kategorie-Wert hat, wodurch angegeben ist, dass der Wert nicht lokalisierbar ist.

Um das Erkennen von lokalisierbaren Elementen in analysierten Dateien, insbesondere in großen Dateien, zu vereinfachen, können Sie die Elemente nach Kategorie, Lesbarkeit und Änderbarkeit sortieren oder filtern. Beispielsweise können Sie nicht lesbare und nicht änderbare Werte herausfiltern.

Übersetzen des lokalisierbaren Inhalts

Verwenden Sie ein beliebiges Tool, das Ihnen zur Verfügung steht, um den extrahierten Inhalt zu übersetzen. Eine gute Vorgehensweise besteht darin, die Ressourcen in eine CSV-Datei zu schreiben, diese in Microsoft Excel anzuzeigen und die Einträge in der letzten Spalte (Value) zu übersetzen.

Verwenden von LocBaml zum Generieren einer neuen .resources.dll-Datei

Die Inhalte, die durch das Analysieren von "HelloApp.resources.dll" mit LocBaml erkannt wurden, sind nun übersetzt und müssen wieder mit der ursprünglichen Anwendung zusammengeführt werden. Verwenden Sie die Option generate oder -g, um eine neue . resources.dll-Datei zu erstellen.

Verwenden Sie die folgende Syntax, um eine neue "HelloApp.resources.dll"-Datei zu generieren. Kennzeichnen Sie die Kultur als "en-US" (/cul:en-US).

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

Hinweis

Wenn sich die Eingabedatei, "HelloApp.resources.dll", nicht im selben Ordner wie die ausführbare Datei, "LocBaml.exe", befindet, verschieben Sie eine der Dateien, damit sich beide Dateien im selben Verzeichnis befinden.
Ersetzen Sie die alte HelloApp.resources.dll-Datei im Verzeichnis C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll durch die neu erstellte HelloApp.resources.dll-Datei.
"Hello World" und "Goodbye World" sollten jetzt in Ihrer Anwendung übersetzt sein.
Um in eine andere Kultur zu übersetzen, verwenden Sie die Kultur der Sprache, in die Sie übersetzen. Das folgende Beispiel zeigt, wie in kanadisches Französisch übersetzt wird:

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
Erstellen Sie in dem Ordner, in dem sich die Hauptanwendungsassembly befindet, einen neuen kulturspezifischen Ordner, der die neue Satellitenassembly aufnehmen soll. Für kanadisches Französisch ist dies der Ordner "fr-CA".
Kopieren Sie die generierte Satellitenassembly in den neuen Ordner.

Um die neue Satellitenassembly zu testen, müssen Sie die Kultur ändern, unter der Ihre Anwendung ausgeführt wird. Dazu haben Sie zwei Möglichkeiten:

Ändern Sie die regionalen Einstellungen Ihres Betriebssystems.

Fügen Sie in Ihrer Anwendung den folgenden Code in "App.xaml.cs" hinzu:

<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

Tipps zum Verwenden von LocBaml

Alle abhängigen Assemblys, die benutzerdefinierte Steuerelemente definieren, müssen in das lokale Verzeichnis von LocBaml kopiert oder im globalen Assemblycache (GAC) installiert werden. Dies ist notwendig, da die Lokalisierungs-API Zugriff auf die abhängigen Assemblys haben muss, wenn sie die binäre XAML (BAML) liest.
Wenn die Hauptassembly signiert ist, muss auch die generierte Ressourcen-DLL signiert sein, damit sie geladen werden kann.
Die Version der lokalisierten Ressourcen-DLL muss mit der Hauptassembly synchronisiert werden.

Freigeben über