Lokalisieren Sie Zeichenketten in der Benutzeroberfläche und im App-Paketmanifest

  • Artikel

Weitere Informationen über den Mehrwert durch die Lokalisierung Ihrer Windows App SDK-App finden Sie unter Globalisierung und Lokalisierung.

Wenn Sie möchten, dass Ihre App verschiedene Anzeigesprachen unterstützt und Ihr Code oder XAML-Markup- oder App-Paketmanifest Zeichenfolgenliterale enthält, verschieben Sie diese Zeichenketten in eine Ressourcendatei (.resw). Sie können dann eine übersetzte Kopie dieser Ressourcendatei für jede Sprache erstellen, die Ihre App unterstützt.

Hartcodierte Zeichenfolgenliterale können im imperativen Code oder im XAML-Markup angezeigt werden, z.B. als Texteigenschaft eines TextBlock-Objekts. Sie können auch in der Quelldatei des App-Paketmanifests (der Package.appxmanifest Datei) angezeigt werden, z. B. als Wert für den Anzeigenamen auf der Anwendungsregisterkarte des Visual Studio-Manifest-Designers. Verschieben Sie diese Zeichenketten in eine Ressourcendatei (.resw), und ersetzen Sie die hartcodierten Zeichenfolgenliterale in Ihrer App und im Manifest durch Verweise auf Ressourcenbezeichner.

Im Gegensatz zu Bildressourcen, bei denen nur eine Bildressource in einer Bildressourcendatei enthalten ist, sind mehrere Zeichenfolgenressourcen in einer Zeichenfolgenressourcendatei enthalten. Eine Zeichenkettenressourcendatei ist eine Ressourcendatei (.resw), und normalerweise erstellen Sie diese Art von Ressourcendatei in einem Ordner \Strings in Ihrem Projekt. Hintergrundinformationen zur Verwendung von Qualifizierern in den Namen Ihrer Ressourcendateien (.resw) finden Sie unter Anpassen Ihrer Ressourcen für Sprache, Skalierung und andere Qualifizierer.

Speichern Sie Zeichenketten in einer Ressourcendatei

  1. Legen Sie die Standardsprache Ihrer Apps fest.

    1. Wenn Ihre Lösung in Visual Studio geöffnet ist, öffnen Sie Package.appxmanifest.
    2. Vergewissern Sie sich auf der Registerkarte Anwendung, dass die Standardsprache richtig eingestellt ist (zum Beispiel „en“ oder „en-US“). Bei den weiteren Schritten wird davon ausgegangen, dass Sie die Standardsprache auf „en-US“ eingestellt haben.

    Hinweis

    Sie müssen mindestens eine Zeichenfolgenressource für die Standardsprache angeben. Diese sind die Ressourcen, die geladen werden, wenn nichts Passenderes für die benutzerseitig bevorzugten Einstellungen für Sprache oder Anzeigesprache gefunden wird.

  2. Erstellen Sie eine Ressourcendatei (.resw) für die Standardsprache.

    1. Erstellen Sie unter Ihrem Projektknoten einen neuen Ordner mit dem Namen Strings.
    2. Erstellen Sie unter Strings einen neuen Unterordner, und nennen Sie ihn en-US.
    3. Erstellen Sie unter en-US eine neue Ressourcendatei (.resw) (unter den WinUI-Dateitypen im Dialogfeld Neues Element hinzufügen) und bestätigen Sie, dass sie den Namen Resources.resw hat.

    Hinweis

    Wenn Sie über .NET Ressourcendateien (.resx) verfügen, die Sie portieren möchten, lesen Sie Portieren von XAML und der Benutzeroberfläche.

  3. Öffnen Sie Resources.resw und fügen Sie diese Zeichenkettenressourcen hinzu.

    Strings/en-US/Resources.resw

    Screenshot of the Add Resource table of the Strings > E N U S > Resources.resw file.

    In diesem Beispiel ist „Greeting“ ein Zeichenketten-Ressourcenbezeichner, auf den Sie in Ihrem Markup verweisen können, wie wir noch zeigen werden. Für den Bezeichner „Greeting“ wird eine Zeichenkette für eine Text-Eigenschaft bereitgestellt, und eine Zeichenkette wird für eine Breiten-Eigenschaft bereitgestellt. „Greeting.Text“ ist ein Beispiel für einen Eigenschaftsbezeichner, da er einer Eigenschaft eines Benutzerfoberflächen-Elements entspricht. Sie können z.B. „Greeting.Foreground“ in der Spalte Name hinzufügen und den Wert auf „Rot“ festlegen. Der Bezeichner „Farewell“ ist ein einfacher Zeichenfolgenressourcenbezeichner; der über keine Untereigenschaften verfügt und kann aus imperativem Code geladen werden, wie wir noch zeigen. Die Spalte Kommentar ist ein guter Ort, um Übersetzern spezielle Anweisungen bereitzustellen.

    Da wir in diesem Beispiel einen einfachen Zeichenketten-Ressourcenbezeichner-Eintrag mit dem Namen „Farewell“ haben, können wir nicht auch Eigenschaftsbezeichner basierend auf demselben Bezeichner haben. Das Hinzufügen von „Farewell.Text“ würde also beim Erstellen von Resources.resw einen Doppelten Eintragsfehler verursachen.

    Bei Ressourcenbezeichnern, die pro Ressourcendatei eindeutig sein müssen, wird die Groß-/Kleinschreibung nicht beachtet. Achten Sie darauf, aussagekräftige Ressourcenbezeichner zu verwenden, um zusätzlichen Kontext für Übersetzer bereitzustellen. Ändern Sie die Ressourcenbezeichner nicht, nachdem die Zeichenkettenressourcen zur Übersetzung gesendet wurden. Lokalisierungsteams verwenden den Ressourcenbezeichner, um Ergänzungen, Löschungen und Aktualisierungen in den Ressourcen nachzuverfolgen. Änderungen an den Ressourcenbezeichnern - auch bekannt als „Verschiebung der Ressourcenbezeichner“ - erfordern eine Neuübersetzung der Zeichenketten, da es so aussieht, als ob Zeichenketten gelöscht und andere hinzugefügt wurden.

Beziehen Sie sich auf einen Zeichenketten-Ressourcenbezeichner aus XAML

Sie verwenden eine x:Uid-Direktive, um einem Steuerelement oder einem anderen Element im Markup einen Zeichenketten-Ressourcenbezeichner zuzuordnen.

<TextBlock x:Uid="Greeting"/>

Zur Laufzeit wird \Strings\en-US\Resources.resw geladen (da das derzeit die einzige Ressourcendatei im Projekt ist). Die x:Uid-Direktive im TextBlock bewirkt, dass ein Nachschlagevorgang stattfindet, um Eigenschaftsbezeichner in Resources.resw zu finden, die den Zeichenketten-Ressourcenbezeichner „Greeting“ enthalten. Die Bezeichner der Eigenschaft „Greeting.Text“ und „Greeting.Width“ werden gefunden, und ihre Werte werden auf den TextBlock angewendet, wobei alle lokal im Markup festgelegten Werte außer Kraft gesetzt werden. Der Wert „Greeting.Foreground“ würde ebenfalls angewendet, wenn Sie diesen hinzugefügt hätten. Es werden jedoch nur Eigenschaftenbezeichner verwendet, um Eigenschaften für XAML-Markupelemente festzulegen, sodass das Festlegen von x:Uid auf „Farewell“ für diesen TextBlock keine Auswirkung hätte. Resources.reswenthält den Zeichenketten-Ressourcenbezeichner „Farewell“, jedoch keine Eigenschaftsbezeichner dafür.

Stellen Sie beim Zuweisen eines Zeichenketten-Ressourcenbezeichners zu einem XAML-Element sicher, dass alle Eigenschaftenbezeichner für diesen Bezeichner für das XAML-Element geeignet sind. Wenn Sie z.B. für einen TextBlockx:Uid="Greeting" festlegen, wird „Greeting.Text“ aufgelöst, da der TextBlock-Typ eine Texteigenschaft aufweist. Wenn Sie jedoch x:Uid="Greeting" auf einer Schaltfläche festlegen, führt „Greeting.Text“ zu einem Laufzeitfehler, da der Schaltflächentyp keine Texteigenschaft aufweist. Eine Lösung für diesen Fall besteht darin, einen Eigenschaftenbezeichner mit dem Namen „ButtonGreeting.Content“ zu erstellen und x:Uid="ButtonGreeting" für die Schaltfläche festzulegen.

Anstatt Breite aus einer Ressourcendatei festzulegen, werden Sie wahrscheinlich erlauben wollen, dass sich die Größe der Steuerelemente dynamisch an den Inhalt anpasst.

Hinweis

Für angefügte Eigenschaften benötigen Sie eine spezielle Syntax in der Spalte Name einer .resw-Datei. Wenn Sie z.B. einen Wert für die angefügte Eigenschaft AutomationProperties.Name für den Bezeichner „Greeting“ festlegen möchten, geben Sie dies in die Spalte Name ein.

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Beziehen Sie sich auf einen Zeichenketten-Ressourcenbezeichner aus Code

Sie können eine Zeichenkettenressource basierend auf einem einfachen Zeichenketten-Ressourcenbezeichner explizit laden.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Sie können diesen Code in einem Klassenbibliothek-Projekt verwenden. In der Runtime werden die Ressourcen der App, die die Bibliothek hostet, geladen. Es wird empfohlen, dass eine Bibliothek Ressourcen aus der App lädt, die sie hostet, da die App wahrscheinlich einen größeren Lokalisierungsgrad aufweist. Wenn eine Bibliothek Ressourcen bereitstellen muss, sollte sie ihrer Hosting-App die Option zur Verfügung stellen, diese Ressourcen als Eingabe zu ersetzen.

Wenn ein Ressourcenname segmentiert ist (er enthält „.“-Zeichen), ersetzen Sie Punkte durch Schrägstriche („/“) im Ressourcennamen. Eigenschaftsbezeichner enthalten z. B. Punkte; Daher müssen Sie diese Ersetzung durchführen, um eines dieser Elemente aus Code zu laden.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

Im Zweifelsfall können Sie MakePri.exe verwenden, um die PRI-Datei Ihrer App zu dumpen. Jede Ressource uri wird in der gedumpten Datei angezeigt.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Verweisen Sie im App-Paketmanifest auf einen Zeichenfolgenressourcenbezeichner.

  1. Öffnen Sie die Quelldatei des App-Paketmanifests (die Package.appxmanifest Datei), in der die App Display name standardmäßig als Zeichenfolgenliteral ausgedrückt wird.

    Screenshot of the Package.appxmanifest file showing the Application tab with the Display name set to Adventure Works Cycles.

  2. Um eine lokalisierbare Version dieser Zeichenkette zu erstellen, öffnen Sie Resources.resw und fügen Sie eine neue Zeichenfolgenressource mit dem Namen „AppDisplayName“ und dem Wert „Adventure Works Cycles“ hinzu.

  3. Ersetzen Sie das Zeichenfolgenliteral des Anzeigenamens durch eine Referenz auf den Zeichenketten-Ressourcenbezeichner, den Sie soeben erstellt haben („AppDisplayName“). Dazu verwenden Sie das ms-resource URI-Schema (Uniform Resource Identifier).

    Screenshot of the Package.appxmanifest file showing the Application tab with the Display name set to M S resource App Display Name.

  4. Wiederholen Sie diesen Vorgang für jede Zeichenkette in Ihrem Manifest, die Sie lokalisieren möchten. Beispielsweise den Kurznamen Ihrer App (den Sie so konfigurieren können, dass er auf der Kachel Ihrer App auf der Startseite angezeigt wird). Eine Liste aller Elemente im App-Paketmanifest, die Sie lokalisieren können, finden Sie unter Lokalisierbare Manifestelemente.

Lokalisieren der Zeichenkettenressourcen

  1. Erstellen Sie eine Kopie Ihrer Ressourcendatei (.resw) für eine andere Sprache.

    1. Erstellen Sie unter „Zeichenketten“ einen neuen Unterordner, und nennen Sie ihn „de-DE“ für Deutsch (Deutschland).

    Hinweis

    Für den Ordnernamen können Sie ein beliebiges BCP-47-Sprachtag verwenden. Unter Anpassen Ihrer Ressourcen an Sprache, Skalierung und andere Qualifizierer finden Sie Einzelheiten zum Sprachqualifizierer und eine Liste gängiger Sprach-Tags. 2. Erstellen Sie eine Kopie von Strings/en-US/Resources.resw im Ordner Strings/de-DE.

  2. Übersetzen Sie die Zeichenketten.

    1. Öffnen Sie Strings/de-DE/Resources.resw und übersetzen Sie die Werte in der Spalte Wert. Die Kommentare müssen Sie nicht übersetzen.

    Strings/de-DE/Resources.resw

    add resource, german

Wenn Sie möchten, können Sie die Schritte 1 und 2 für eine weitere Sprache wiederholen.

Strings/fr-FR/Resources.resw

add resource, french

Testen Sie Ihre App

Testen Sie die App für Ihre Standardanzeigesprache. Anschließend können Sie die Anzeigesprache in Einstellungen> Time & Language>Region & Language>Languages ändern und Ihre App erneut testen. Sehen Sie sich Zeichenketten auf Ihrer Benutzeroberfläche und auch in der Shell an (z.B. die Titelleiste - also Ihren Anzeigenamen - und den Kurznamen auf ihren Kacheln).

Hinweis

Wenn ein Ordnername gefunden werden kann, der den Einstellungen der Anzeigesprache entspricht, wird die Ressourcendatei innerhalb dieses Ordners geladen. Andernfalls findet ein Fallback statt, der mit den Ressourcen für die Standardsprache Ihrer App endet.

Aufteilen von Zeichenketten in mehrere Ressourcendateien

Sie können alle Zeichenketten in einer einzelnen Ressourcendatei (resw) speichern, oder Sie können sie über mehrere Ressourcendateien hinweg aufteilen. Sie könnten zum Beispiel Ihre Fehlermeldungen in einer Ressourcendatei, die Zeichenketten des App-Paketmanifests in einer anderen und die Zeichenketten der Benutzeroberfläche in einer dritten Datei speichern wollen. In diesem Fall würde ihre Ordnerstruktur so aussehen.

Screenshot of the Solution panel showing the Adventure Works Cycles > Strings folder with German, U S English, and French locale folders and files.

Um einen Zeichenketten-Ressourcenbezeichner auf eine bestimmte Datei zu beschränken, fügen Sie /<resources-file-name>/ direkt vor dem Bezeichner hinzu. Im folgenden Markupbeispiel wird davon ausgegangen, dass ErrorMessages.resw eine Ressource enthält, deren Name „PasswordTooWeak.Text“ lautet und dessen Wert den Fehler beschreibt.

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Sie müssen nur /<resources-file-name>/ vor dem Zeichenketten-Ressourcenbezeichner für Ressourcendateien andere alsResources.resw hinzufügen. Der Grund dafür ist, dass „Resources.resw“ der Standarddateiname ist, der angenommen wird, wenn Sie einen Dateinamen weglassen (wie in den vorherigen Beispielen in diesem Thema beschrieben).

Das folgende Codebeispiel geht davon aus, dass ErrorMessages.resw eine Ressource mit dem Namen „MismatchedPasswords“ enthält, deren Wert den Fehler beschreibt.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Wenn Sie Ihre „AppDisplayName“-Ressource aus Resources.resw und in ManifestResources.resw verschieben würden, dann würden Sie in Ihrem App-Paketmanifest ms-resource:AppDisplayName zu ms-resource:/ManifestResources/AppDisplayName ändern.

Wenn der Name einer Ressourcendatei segmentiert ist (er enthält „.“-Zeichen), dann lassen Sie die Punkte im Namen, wenn Sie darauf verweisen. Ersetzen Sie keine Punkte durch Schrägstrich-Zeichen („/“), wie sie für einen Ressourcennamen verwendet werden sollen.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("Err.Msgs");

Im Zweifelsfall können Sie MakePri.exe verwenden, um die PRI-Datei Ihrer App zu dumpen. Jede Ressource uri wird in der gedumpten Datei angezeigt.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Laden einer Zeichenkette für eine bestimmte Sprache oder einen anderen Kontext

Der Standardmäßige ResourceContext (beim Erstellen eines ResourceLoader erhalten) enthält einen Qualifiziererwert für jeden Qualifizierernamen, der den Standardlaufzeitkontext darstellt (d.h. die Einstellungen für den aktuellen Benutzer und den aktuellen Computer). Ressourcendateien (.resw) werden – basierend auf den Qualifizierern in ihren Namen – mit den Qualifiziererwerten in diesem Laufzeitkontext übereinstimmen.

Es kann jedoch vorkommen, dass Sie möchten, dass Ihre App die Systemeinstellungen außer Kraft setzt und explizit die Sprache, die Skalierung oder einen anderen Qualifizierungswert angibt, der bei der Suche nach einer passenden Ressourcendatei zum Laden verwendet werden soll. Sie möchten zum Beispiel, dass Ihre Benutzer eine andere Sprache für Tooltips oder Fehlermeldungen auswählen können.

Sie können dies tun, indem Sie einen neuen ResourceContext erstellen, dessen Werte übergehen und dann dieses Kontextobjekt in Ihren Zeichenketten-Verweisen verwenden.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

Die Verwendung von QualifierValues wie im obigen Codebeispiel funktioniert für jeden Qualifizierer. Für den speziellen Fall der Sprache können Sie dies alternativ verwenden.

resourceContext.Languages = new string[] { "de-DE" };

Laden von Zeichenketten aus einer Klassenbibliothek

Die Zeichenfolgenressourcen einer referenzierten Klassenbibliothek werden in der Regel in einen Unterordner des Pakets hinzugefügt, in dem sie während des Buildprozesses enthalten sind. Der Ressourcenbezeichner einer solchen Zeichenkette verwendet in der Regel die Form LibraryName/ResourcesFileName/ResourceIdentifier.

Eine Bibliothek kann einen ResourceLoader für eigene Ressourcen abrufen. Der folgende Code veranschaulicht beispielsweise, wie eine Bibliothek oder eine App, die darauf verweist, einen ResourceLoader für die Zeichenkettenressourcen der Bibliothek abrufen kann.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

Wenn Sie Zweifel an dem Pfad haben, können Sie MakePri.exe-Befehlszeilenoptionen angeben, um die PRI-Datei Ihrer Komponente oder Bibliothek zu dumpen. Jede Ressource uri wird in der gedumpten Datei angezeigt.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Laden von Zeichenketten aus anderen Paketen

Die Ressourcen für ein App-Paket werden verwaltet und über die eigene ResourceMap auf oberster Ebene des Pakets aufgerufen, auf die über den ResourceManager zugegriffen werden kann. Innerhalb jedes Pakets können verschiedene Komponenten über eigene ResourceMap-Unterstrukturen verfügen, auf die Sie über ResourceMap.GetSubtree zugreifen können.

Ein Frameworkpaket kann auf eigene Ressourcen mit einem absoluten Ressourcenbezeichner-URI zugreifen. Weitere Informationen finden Sie auch unter URI-Schemata in der UWP-Dokumentation.

Laden von Zeichenketten in ungepackten Anwendungen

Ab Windows Version 1903 (Update vom Mai 2019) können ungepackte Anwendungen auch das Ressourcenverwaltungssystem nutzen.

Erstellen Sie einfach Ihre Windows App SDK-Benutzersteuerelemente/-bibliotheken, und speichern Sie alle Zeichenketten in einer Ressourcendatei. Sie können dann auf einen Zeichenketten-Ressourcenbezeichner aus XAML verweisen, auf einen String-Ressourcenbezeichner aus dem Code verweisen oder Strings aus einer Klassenbibliothek laden.

Wenn Sie Ressourcen in ungepackten Anwendungen verwenden möchten, sollten Sie einige Aktionen ausführen:

  1. Verwenden Sie den überschriebenen Konstruktor von ResourceManager, um den Dateinamen der .pri-Datei Ihrer App zu übernehmen, wenn Sie Ressourcen aus dem Code auflösen, da es in ungepackten Szenarien keine Standardansicht gibt.
  2. Verwenden Sie MakePri.exe, um die Datei resources.pri Ihrer App manuell zu generieren.
    • Ausführen von makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri
    • Der <PRICONFIG> muss den Abschnitt „<Packaging>“ weglassen, damit alle Ressourcen in einer einzigen resources.pri-Datei gebündelt werden. Wenn Sie die Standard MakePri.exe Konfigurationsdatei verwenden, die von createconfig erstellt wurde, müssen Sie den Abschnitt „<Verpackung>“ nach der Erstellung manuell löschen.
    • Der <PRICONFIG> muss alle relevanten Indexer enthalten, die zum Zusammenführen aller Ressourcen in Ihrem Projekt in einer einzigen resources.pri-Datei erforderlich sind. Die MakePri.exe-Standardkonfigurationsdatei, die von createconfig erstellt wird, enthält alle Indexer.
    • Wenn Sie die Standardkonfiguration nicht verwenden, stellen Sie sicher, dass der PRI-Indexer aktiviert ist (überprüfen Sie die Standardkonfiguration für die Vorgehensweise), um PRIs, die aus Projektverweisen, NuGet-Verweisen usw. gefunden wurden, zusammenzuführen, die sich im Projektstamm befinden.

      Hinweis

      Durch das Weglassen von /IndexName, und dadurch, dass das Projekt kein App-Manifest hat, wird der IndexName/Wurzel-Namensraum der PRI-Datei automatisch auf Application gesetzt, was die Laufzeitumgebung unter ungepackten Apps versteht (dadurch wird die vorherige harte Abhängigkeit von der Paket-ID aufgehoben). Bei der Angabe von Ressourcen-URIs schließen ms-resource:///-Referenzen, die den Root-Namespace auslassen, auf die Anwendung als Root-Namespace für ungepackte Anwendungen (oder Sie können die Anwendung explizit angeben, wie in ms-resource://Application/).

  3. Kopieren Sie die PRI-Datei in das Buildausgabeverzeichnis der .exe-Datei.
  4. Führen Sie die .exe-Datei aus

    Hinweis

    Das Ressourcenverwaltungssystem verwendet die Anzeigesprache des Systems und nicht die vom Benutzer bevorzugte Sprachliste, wenn es Ressourcen in ungepackten Anwendungen anhand der Sprache auflöst. Die vom Benutzer bevorzugte Sprachliste wird nur für verpackte Windows App SDK-Apps verwendet.

Wichtig

Sie müssen PRI-Dateien immer dann manuell neu erstellen, wenn Ressourcen geändert werden. Wir empfehlen die Verwendung eines Post-Build-Skripts, das den Befehl MakePri.exe verarbeitet und die resources.pri-Ausgabe in das Verzeichnis .exe kopiert.

Wichtige APIs

Siehe auch