Vorgehensweise: Lokalisieren einer Anwendung

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.

  1. Entwickeln Sie Ihre Anwendung bis zu dem Punkt, an dem Sie die Lokalisierung starten möchten.

  2. 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>

  3. 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:

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

    msbuild helloapp.csproj

  2. Die neu erstellte Hauptanwendungsassembly, "HelloApp.exe", wird im folgenden Ordner erstellt: C:\HelloApp\Bin\Debug

  3. 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

  1. 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.

  2. Führen Sie über die Befehlszeile die Projektdatei (locbaml.csproj) aus, um das Tool zu erstellen:

    msbuild locbaml.csproj

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

  4. 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.

  1. Kopieren Sie "LocBaml.exe" in den "bin\debug"-Ordner Ihrer Anwendung, in dem die Hauptanwendungsassembly erstellt wurde.

  2. 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.

  3. 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 Kommentare 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.

  4. 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.

  1. 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.

  2. 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.

  3. "Hello World" und "Goodbye World" sollten jetzt in Ihrer Anwendung übersetzt sein.

  4. 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

  5. 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".

  6. Kopieren Sie die generierte Satellitenassembly in den neuen Ordner.

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

Weitere Informationen