So geht's: Eine Anwendung lokalisieren

Artikel
2025-01-30

In diesem Lernprogramm wird erläutert, wie Sie mithilfe des LocBaml-Tools eine lokalisierte Anwendung erstellen.

Anmerkung

Das LocBaml-Tool ist keine produktionsfertige Anwendung. Es wird als Beispiel dargestellt, das einige der Lokalisierungs-APIs verwendet und veranschaulicht, wie Sie ein Lokalisierungstool schreiben können.

Überblick

In diesem Artikel erhalten Sie einen schrittweisen Ansatz zum Lokalisieren einer Anwendung. Zunächst bereiten Sie Ihre Anwendung so vor, dass der übersetzte Text extrahiert werden kann. Nachdem der Text übersetzt wurde, integrieren Sie den übersetzten Text in eine neue Kopie der ursprünglichen Anwendung.

Erstellen einer Beispielanwendung

In diesem Schritt bereiten Sie Ihre App für die Lokalisierung vor. In den Windows Presentation Foundation (WPF)-Beispielen wird ein HelloApp-Beispiel mitgeliefert, das 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) aus dem LocBaml-Toolbeispielherunter.

Entwickeln Sie Ihre Anwendung an dem Punkt, an dem Sie mit der Lokalisierung beginnen 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 lautet "HelloApp.csproj". In dieser Datei finden Sie die wie folgt identifizierte Entwicklungssprache:

<UICulture>en-US</UICulture>
Fügen Sie den XAML-Dateien UIDs hinzu. Uids werden verwendet, um Änderungen an Dateien nachzuverfolgen und 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, um eine Dynamic Link Library (DLL) zu erstellen:

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 Sie das LocBaml-Tool.

Alle zum Erstellen von LocBaml erforderlichen Dateien befinden sich in den WPF-Beispielen. Laden Sie die C#-Dateien aus dem LocBaml-Toolbeispielherunter.
Führen Sie in der 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 zu finden (locbaml.exe). Beispiel: C:\LocBaml\Bin\Release\locbaml.exe

Die Optionen, die Sie beim Ausführen von LocBaml angeben können, sind wie folgt.

Option	Beschreibung
`parse` oder `-p`	Analysiert Baml-, Ressourcen- oder DLL-Dateien, um eine .csv- oder .txt-Datei zu generieren.
`generate` oder `-g`	Generiert eine lokalisierte Binärdatei mithilfe einer übersetzten Datei.
`out` oder `-o` {filedirectory]	Ausgabedateiname.
`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`	Zeigt keine Logo- oder Copyrightinformationen an.
`verbose`	Bewirkt, dass Informationen im ausführlichen Modus angezeigt werden

Anmerkung

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 die Eingabetaste.

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 Ordner "bin\debug" 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:

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

Anmerkung

Wenn sich die Eingabedatei HelloApp.resources.dllnicht im gleichen Verzeichnis befindet wie LocBaml.exe eine der Dateien verschieben, sodass sich beide Dateien im selben Verzeichnis befinden.

Wenn Sie LocBaml zum Analysieren von Dateien ausführen, besteht die Ausgabe aus sieben Feldern, die durch Kommas (für.csv-Dateien) oder Tabulatoren (für.txt-Dateien) getrennt sind. Nachstehend wird 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 Lokalisierer gelesen werden kann. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Änderbarkeit Gibt an, ob der Wert von einem Lokalisierer geändert werden kann. Weitere Informationen finden Sie unter Lokalisierungsattribute und -kommentare.
Kommentare Zusätzliche Beschreibung des Werts, um zu bestimmen, 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	Modifizierbarkeit	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	Nichts	TRUE	TRUE	Hallo Welt
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Nichts	TRUE	TRUE	Auf Wiedersehen Welt

Beachten Sie, dass alle Werte für das Feld Comments keine Werte enthalten; Wenn ein Feld keinen Wert aufweist, ist es leer. Beachten Sie außerdem, dass das Element in der ersten Zeile weder lesbar noch modifizierbar ist und den Wert "Ignorieren" als Category-Wert aufweist, was alles darauf hinweist, dass der Wert nicht lokalisierbar ist.

Um die Ermittlung lokalisierbarer Elemente in analysierten Dateien, insbesondere in großen Dateien, zu erleichtern, können Sie die Elemente nach Kategorie-, Lesbarkeitund Modifizierbarkeitsortieren oder filtern. Sie können z. B. unlesbare und unveränderliche Werte herausfiltern.

Übersetzen des lokalisierbaren Inhalts

Verwenden Sie jedes Tool, das Sie zum Übersetzen des extrahierten Inhalts zur Verfügung haben. 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 (Wert) zu übersetzen.

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

Der Inhalt, der durch die Analyse von HelloApp.resources.dll mit LocBaml identifiziert wurde, wurde übersetzt und muss wieder mit der ursprünglichen Anwendung zusammengeführt werden. Verwenden Sie die Option generate oder -g, um eine neue .resources.dll Datei zu generieren.

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

Anmerkung

Wenn sich die Eingabedatei, Hello.csv, nicht im gleichen Verzeichnis wie die ausführbare Datei befindet, LocBaml.exe, verschieben Sie eine der Dateien so, dass 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 werden.
Um in eine andere Kultur zu übersetzen, nutzen Sie die kulturellen Aspekte der Sprache, in die Sie übersetzen. Das folgende Beispiel zeigt, wie man ins kanadische Französisch übersetzt:

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. Sie können dies auf eine von zwei Arten tun:

Ändern Sie die regionalen Einstellungen Ihres Betriebssystems.

Fügen Sie in Ihrer Anwendung den folgenden Code zur App.xaml.cs-Datei 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 für die Verwendung 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 erforderlich, da die Lokalisierungs-API Zugriff auf die abhängigen Assemblys haben muss, wenn sie den binären XAML-Code (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