Freigeben über

Lokalisierung für Office-Add-Ins

  • Artikel

Sie können für Ihre Office-Add-In ein Lokalisierungsschema Ihrer Wahl implementieren. Die JavaScript-API und das Manifestdateischema der Office-Add-Ins-Plattform bieten verschiedene Optionen. Sie können die Office JavaScript-API verwenden, um ein Gebietsschema und Anzeigezeichenfolgen basierend auf dem Gebietsschema der Office-Anwendung zu bestimmen oder Daten basierend auf dem Gebietsschema der Daten zu interpretieren oder anzuzeigen. Mithilfe der Manifestdatei können Sie einen gebietsschemaspezifischen Speicherort für die Add-in-Datei und beschreibende Informationen angeben. Alternativ können Sie visual Studio und Das Microsoft Ajax-Skript verwenden, um Globalisierung und Lokalisierung zu unterstützen.

Bestimmen gebietsschemaspezifischer Zeichenfolgen mithilfe der JavaScript-API

Die Office JavaScript-API bietet zwei Eigenschaften, die das Anzeigen oder Interpretieren von Werten unterstützen, die mit dem Gebietsschema der Office-Anwendung und -Daten konsistent sind.

  • Context.displayLanguage gibt das Gebietsschema (oder die Sprache) der Benutzeroberfläche der Office-Anwendung an. Im folgenden Beispiel wird überprüft, ob die Office-Anwendung das Gebietsschema en-US oder fr-FR verwendet, und zeigt eine gebietsschemaspezifische Begrüßung an.

    function sayHelloWithDisplayLanguage() {
    const myLanguage = Office.context.displayLanguage;
    switch (myLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'fr-FR':
            write('Bonjour!');
            break;
    }
}

// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

  • Context.contentLanguage gibt das Gebietsschema (oder die Sprache) der Daten an. Wenn Sie das letzte Codebeispiel erweitern, anstatt die displayLanguage-Eigenschaft zu überprüfen, weisen Sie myLanguage den Wert der contentLanguage-Eigenschaft zu, und verwenden Sie den restlichen Code, um eine Begrüßung basierend auf dem Gebietsschema der Daten anzuzeigen.

    const myLanguage = Office.context.contentLanguage;

Steuern der Lokalisierung in der Manifestdatei

Die Verfahren für die Lokalisierung mit dem Manifest unterscheiden sich je nachdem, ob Sie das reine Add-In-Manifest oder das einheitliche App-Manifest für Microsoft 365 verwenden.

Wenn Sie das einheitliche App-Manifest für Microsoft 365 verwenden, lokalisieren Sie die öffentlich zugänglichen Zeichenfolgen im Manifest, wie unter Lokalisieren von Zeichenfolgen in Ihrem App-Manifest beschrieben. Es folgt ein Beispiel für ein Outlook-Add-In. Zuerst ist das "localizationInfo"-Objekt im Manifest. Darunter befindet sich die fr-fr.json-Datei mit den übersetzten Zeichenfolgen. Das Add-In verfügt über einen Aufgabenbereich (mit einer französischen Version der Startseite), lokalisierte französische Symbole und eine benutzerdefinierte Menübandschaltfläche, die einen Videoplayer in einem Dialogfeld öffnet.

"localizationInfo": {
  "defaultLanguageTag": "en",
  "additionalLanguages": [
    {
      "languageTag": "fr-fr",
      "file": "fr-fr.json"
    }
  ]
}

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.Localization.schema.json",
  "name.short": "Lecteur vidéo",
  "name.full": "Lecteur vidéo pour Outlook",
  "description.short": "Voir les vidéos YouTube dans Outlook via les mails.",
  "description.full": "Visualisez les vidéos YouTube référencées dans vos courriers électronique directement depuis Outlook.",
  "icons.color": "https://localhost:3000/assets/fr-fr/icon-128.png",
  "extensions[0].audienceClaimUrl": "https://localhost:3000/fr-fr/taskpane.html",
  "extensions[0].ribbons[0].tabs[0].groups[0].label": "Outils de médias",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].icons[0].url": "https://localhost:3000/assets/fr-fr/player-icon.png",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].label": "Ouvrir le lecteur vidéo",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.description": "Cliquez pour ouvrir le lecteur vidéo.",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.title": "Ouvrir le lecteur vidéo",
}

Abgleichen des Datum-/Uhrzeitformats mit dem Clientgebietsschema

Sie können das Gebietsschema der Benutzeroberfläche der Office-Clientanwendung mithilfe der displayLanguage-Eigenschaft abrufen. Anschließend können Sie Datums- und Uhrzeitwerte in einem Format anzeigen, das mit dem aktuellen Gebietsschema der Office-Anwendung übereinstimmt. Eine Möglichkeit hierfür ist das Vorbereiten einer Ressourcendatei, die das zu verwendende Datum-/Uhrzeitformat für jedes Gebietsschema angibt, das Ihr Office-Add-In unterstützt. Zur Laufzeit kann Ihr Add-In die Ressourcendatei verwenden und das entsprechende Datums-/Uhrzeitformat mit dem Gebietsschema abgleichen, das von der displayLanguage-Eigenschaft abgerufen wurde.

Sie können das Gebietsschema der Daten der Office-Clientanwendung mithilfe der contentLanguage-Eigenschaft abrufen. Basierend auf diesem Wert können anschließend Datums-/Uhrzeitzeichenfolgen entsprechend interpretiert oder angezeigt werden. Im Gebietsschema jp-JP werden Datums-/Uhrzeitwerte im Format yyyy/MM/ddfr-FR beispielsweise im Format dd/MM/yyyy ausgedrückt.

Verwenden von Visual Studio zum Erstellen eines lokalisierten und globalisierten Add-Ins

Wenn Sie zum Erstellen von Office-Add-Ins mit Visual Studio arbeiten, bieten .NET Framework und Ajax Möglichkeiten zum Globalisieren und Lokalisieren von Clientskriptdateien.

Sie können die JavaScript-Typerweiterungen Date und Number und das JavaScript-Objekt Date im JavaScript-Code für eine Office-Add-In verwenden, um Werte basierend auf den Gebietsschemaeinstellungen im aktuellen Browser anzuzeigen. Weitere Informationen finden Sie unter Walkthrough: Globalizing a Date by Using Client Script.

Sie können lokalisierte Ressourcenzeichenfolgen direkt in eigenständige JavaScript-Dateien einbeziehen, um Clientskriptdateien für verschiedene Gebietsschemas bereitzustellen, die im Browser festgelegt oder vom Benutzer angegeben werden. Erstellen Sie für jedes unterstützte Gebietsschema eine eigene Skriptdatei. Fügen Sie jeder Skriptdatei ein Objekt im JSON-Format hinzu, das die Ressourcenzeichenfolgen für das jeweilige Gebietsschema enthält. Die lokalisierten Werte werden übernommen, wenn das Skript im Browser ausgeführt wird.

Beispiel: Erstellen eines lokalisierten Office-Add-Ins

Dieser Abschnitt enthält Beispiele, die das Lokalisieren einer Beschreibung, eines Anzeigenamens und einer Benutzeroberfläche für Office-Add-In veranschaulichen.

Hinweis

Informationen zum Herunterladen von Visual Studio finden Sie auf der Seite Visual Studio-IDE. Während der Installation müssen Sie die Arbeitslast für die Office/SharePoint-Entwicklung auswählen.

Konfigurieren von Office für die Verwendung zusätzlicher Anzeige- oder Bearbeitungssprachen

Um den bereitgestellten Beispielcode auszuführen, konfigurieren Sie Office auf Ihrem Computer für die Verwendung zusätzlicher Sprachen, damit Sie Ihr Add-In testen können, indem Sie die Sprache wechseln, die für die Anzeige in Menüs und Befehlen, für die Bearbeitung und Korrektur oder beides verwendet wird.

Sie können ein Office Language Pack verwenden, um eine weitere Sprache zu installieren. Weitere Informationen zu Sprachpaketen und wo Sie diese erhalten finden Sie unter Language Accessory Pack für Office.

Nachdem Sie das Language Accessory Pack installiert haben, können Sie Office für die Verwendung der installierten Sprache in der Benutzeroberfläche, bei der Bearbeitung von Dokumentinhalten und/oder beidem konfigurieren. Beim Beispiel in diesem Artikel wird eine Installation von Office mit dem spanischen Sprachpaket verwendet.

Erstellen eines Office-Add-In-Projekts

Sie müssen ein Visual Studio Office-Add-In-Projekt erstellen.

Hinweis

Wenn Sie Visual Studio noch nicht installiert haben, finden Sie auf der Seite Visual Studio-IDE Anweisungen zum Download. Während der Installation müssen Sie die Arbeitslast für die Office/SharePoint-Entwicklung auswählen. Wenn Sie Visual Studio 2019 oder höher bereits installiert haben, verwenden Sie die Visual Studio-Installer, um sicherzustellen, dass die Workload Office/SharePoint-Entwicklung installiert ist.

  1. Wählen Sie Neues Projekt erstellen aus.

  2. Geben Sie Add-In in das Suchfeld ein. Wählen Sie Word-Web-Add-In und dann Weiter aus.

  3. Nennen Sie Ihr Projekt WorldReadyAddIn , und wählen Sie Erstellen aus.

  4. Visual Studio erstellt eine Projektmappe, und die beiden Projekte werden im Projektmappen-Explorer angezeigt. Die Datei Home.html wird in Visual Studio geöffnet.

Lokalisieren des Texts im Add-in

Der Text, den Sie für eine andere Sprache lokalisieren möchten, wird in zwei Bereichen angezeigt.

  • Add-in-Anzeigename und -Beschreibung. Dies wird durch die Einträge in der Add-in-Manifestdatei gesteuert.

  • Add-In-UI. Die Zeichenfolgen, die auf der Benutzeroberfläche Ihres Add-Ins angezeigt werden, können mithilfe von JavaScript-Code lokalisiert werden – beispielsweise unter Verwendung einer separaten Ressourcendatei mit den lokalisierten Zeichenfolgen.

Lokalisieren des Anzeigenamens und der Beschreibung des Add-Ins

  1. Erweitern Sie im Projektmappen-Explorer die Option WorldReadyAddIn, dann WorldReadyAddInManifest, und wählen Sie schließlich WorldReadyAddIn.xml aus.

  2. Ersetzen Sie inWorldReadyAddInManifest.xmldie Elemente DisplayName und Description durch den folgenden Codeblock.

    Hinweis

    Die in spanischer Sprache lokalisierten Zeichenfolgen für die Elemente DisplayName und Description in diesem Beispiel können durch lokalisierte Zeichenfolgen für eine beliebige Sprache ersetzt werden.

    <DisplayName DefaultValue="World Ready add-in">
  <Override Locale="es-es" Value="Aplicación de uso internacional"/>
</DisplayName>
<Description DefaultValue="An add-in for testing localization">
  <Override Locale="es-es" Value="Una aplicación para la prueba de la localización"/>
</Description>

  3. Wenn Sie beispielsweise die Anzeigesprache für Microsoft 365 von Englisch in Spanisch ändern und dann das Add-In ausführen, werden der Anzeigename und die Beschreibung des Add-Ins mit lokalisiertem Text angezeigt.

Layout der Add-In-Benutzeroberfläche

  1. Wählen Sie in Visual Studio im Projektmappen-Explorer die Option Home.html aus.

  2. Ersetzen Sie den <body> Elementinhalt in Home.html durch den folgenden HTML-Code, und speichern Sie die Datei.

    <body>
    <!-- Page content -->
    <div id="content-header" class="ms-bgColor-themePrimary ms-font-xl">
        <div class="padding">
            <h1 id="greeting" class="ms-fontColor-white"></h1>
        </div>
    </div>
    <div id="content-main">
        <div class="padding">
            <div class="ms-font-m">
                <p id="about"></p>
            </div>
        </div>
    </div>
</body>

Die folgende Abbildung zeigt das Kopfzeilenelement (h1) und das Absatzelement (p), für die nach dem Ausführen der verbleibenden Schritte und des Add-Ins lokalisierter Text angezeigt wird.

App-Benutzeroberfläche mit hervorgehobenen Abschnitten.

Hinzufügen der Ressourcendatei mit den lokalisierten Zeichenfolgen

Die JavaScript-Ressourcendatei enthält die Zeichenfolgen, die für die Add-In-Benutzeroberfläche verwendet werden. Der HTML-Code für die Beispiel-Add-In-Benutzeroberfläche enthält ein <h1>-Element, das eine Begrüßung anzeigt, und ein <p>-Element, mit dem das Add-In beim Benutzer eingeführt wird.

Positionieren Sie zum Aktivieren lokalisierter Zeichenfolgen für die Überschriften und Absätze die Zeichenfolgen in einer separaten Ressourcendatei. Die Ressourcendatei erstellt ein JavaScript-Objekt, das ein separates JavaScript Object Notation (JSON)-Objekt für jeden Satz lokalisierter Zeichenfolgen enthält. Die Ressourcendatei stellt auch eine Methode zum Abrufen des entsprechenden JSON-Objekts für ein bestimmtes Gebietsschema bereit.

Hinzufügen der Ressourcendatei zum Add-In-Projekt

  1. Klicken Sie in Projektmappen-Explorer in Visual Studio mit der rechten Maustaste auf das Projekt WorldReadyAddInWeb (oder wählen Sie es aus, und halten Sie es gedrückt), und wählen Sie dannNeues Elementhinzufügen> aus.

  2. Wählen Sie im Dialogfeld Neues Element hinzufügenJavaScript-Datei.

  3. Geben Sie UIStrings.js als Dateiname ein und wählen Sie Hinzufügen.

  4. Fügen Sie der UIStrings.js-Datei den folgenden Code hinzu, und speichern Sie die Datei.

    /* Store the locale-specific strings */

const UIStrings = (() => {
    "use strict";

    const UIStrings = {};

    // JSON object for English strings
    UIStrings.EN = {
        "Greeting": "Welcome",
        "Introduction": "This is my localized add-in."
    };

    // JSON object for Spanish strings
    UIStrings.ES = {
        "Greeting": "Bienvenido",
        "Introduction": "Esta es mi aplicación localizada."
    };

    UIStrings.getLocaleStrings = (locale) => {
        let text;

        // Get the resource strings that match the language.
        switch (locale) {
            case 'en-US':
                text = UIStrings.EN;
                break;
            case 'es-ES':
                text = UIStrings.ES;
                break;
            default:
                text = UIStrings.EN;
                break;
        }

        return text;
    };

    return UIStrings;
})();

Die UIStrings.js Ressourcendatei erstellt das Objekt UIStrings, das die lokalisierten Zeichenfolgen für die Add-In-Benutzeroberfläche enthält.

Lokalisieren des Texts für die Add-in-Benutzeroberfläche

Um die Ressourcendatei in Ihrem Add-In zu verwenden, müssen Sie auf Home.htmlein Skripttag hinzufügen. Wenn Home.html geladen wird, wirdUIStrings.js ausgeführt, und das UIStrings-Objekt , das Sie zum Abrufen der Zeichenfolgen verwenden, ist für Ihren Code verfügbar. Fügen Sie den folgenden HTML-Code im Head-Tag für Home.html hinzu, um UIStrings für Ihren Code verfügbar zu machen.

<!-- Resource file for localized strings: -->
<script src="../UIStrings.js" type="text/javascript"></script>

Sie können jetzt das Objekt UIStrings verwenden, um die Zeichenfolgen für die Benutzeroberfläche Ihres Add-Ins festzulegen.

Wenn Sie die Lokalisierung für Ihr Add-In basierend darauf ändern möchten, welche Sprache für die Anzeige in Menüs und Befehlen in der Office-Clientanwendung verwendet wird, verwenden Sie die Office.context.displayLanguage-Eigenschaft , um das Gebietsschema für diese Sprache abzurufen. Wenn die Anwendungssprache beispielsweise Spanisch für die Anzeige in Menüs und Befehlen verwendet, gibt die Office.context.displayLanguage-Eigenschaft den Sprachcode es-ES zurück.

Wenn Sie die Lokalisierung für Ihr Add-In basierend darauf ändern möchten, welche Sprache zum Bearbeiten von Dokumentinhalten verwendet wird, verwenden Sie die Office.context.contentLanguage-Eigenschaft , um das Gebietsschema für diese Sprache abzurufen. Wenn die Anwendungssprache beispielsweise Spanisch zum Bearbeiten von Dokumentinhalten verwendet, gibt die Office.context.contentLanguage-Eigenschaft den Sprachcode es-ES zurück.

Nachdem Sie die Sprache kennen, die die Anwendung verwendet, können Sie UIStrings verwenden, um den Satz lokalisierter Zeichenfolgen abzurufen, der der Anwendungssprache entspricht.

Ersetzen Sie den Code in der Home.js-Datei durch den folgenden Code. Der Code zeigt, wie Sie die in den UI-Elementen verwendeten Zeichenfolgen auf Home.html basierend auf der Anzeigesprache der Anwendung oder der Bearbeitungssprache der Anwendung ändern können.

Hinweis

Um zwischen der Änderung der Lokalisierung des Add-Ins basierend auf der für die Bearbeitung verwendeten Sprache zu wechseln, heben Sie die Auskommentierung der Codezeile const myLanguage = Office.context.contentLanguage; auf, und kommentieren Sie die Codezeile aus. const myLanguage = Office.context.displayLanguage;

/// <reference path="../App.js" />
/// <reference path="../UIStrings.js" />


(() => {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.onReady(() => {
        $(document).ready(() => {
            // Get the language setting for editing document content.
            // To test this, uncomment the following line and then comment out the
            // line that uses Office.context.displayLanguage.
            // const myLanguage = Office.context.contentLanguage;
    
            // Get the language setting for UI display in the Office application.
            const myLanguage = Office.context.displayLanguage;
            let UIText;
    
            // Get the resource strings that match the language.
            // Use the UIStrings object from the UIStrings.js file
            // to get the JSON object with the correct localized strings.
            UIText = UIStrings.getLocaleStrings(myLanguage);
    
            // Set localized text for UI elements.
            $("#greeting").text(UIText.Greeting);
            $("#about").text(UIText.Introduction);
        });
    });
})();

Testen Sie Ihres lokalisierten Add-ins

Um Ihr lokalisiertes Add-In zu testen, ändern Sie die Sprache, die für die Anzeige oder Bearbeitung in der Office-Anwendung verwendet wird, und führen Sie dann Ihr Add-In aus.

  1. Wählen Sie in Word Datei>Optionen>Sprache. Die folgende Abbildung zeigt das Dialogfeld Word-Optionen mit der geöffneten Registerkarte „Sprache“.

    Word Dialogfeld

  2. Wählen Sie unter Anzeigesprache auswählen die Sprache, die für die Anzeige verwendet werden soll, z. B. Spanisch, und wählen Sie dann den Pfeil nach oben, um die spanische Sprache an die erste Position der Liste zu setzen. Alternativ können Sie die für die Bearbeitung verwendete Sprache ändern, indem Sie unter Bearbeitungssprachen auswählen die Sprache auswählen, die Sie für die Bearbeitung verwenden möchten, z. B. Spanisch, und wählen Sie dann Als Standard festlegen aus.

  3. Klicken Sie auf OK, um die getroffene Auswahl zu bestätigen, und schließen Sie Word.

  4. Drücken Sie F5 in Visual Studio, um das Beispiel-Add-In auszuführen, oder wählen Sie Debuggen>Debuggen starten in der Menüleiste.

  5. Wählen Sie in Word Start>Aufgabenbereich anzeigen.

Nach der Ausführung ändern sich die Zeichenfolgen in der Add-In-Benutzeroberfläche so, dass sie der sprache entsprechen, die von der Anwendung verwendet wird, wie in der folgenden Abbildung dargestellt.

App mit lokalisiertem Benutzeroberflächentext.

Siehe auch