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 Manifest für Microsoft 365 verwenden, das nur in Outlook unterstützt wird.

Jedes Office-Add-In gibt ein DefaultLocale-Element und ein Gebietsschema im Manifest an. Standardmäßig wenden die Office-Add-In-Plattform und die Office-Clientanwendungen die Werte der Elemente Description, DisplayName, IconUrl, HighResolutionIconUrl und SourceLocation auf alle Gebietsschemas an. Optional können Sie bestimmte Werte für bestimmte Gebietsschemas unterstützen, indem Sie für jedes weitere Gebietsschema ein untergeordnetes Element außer Kraft setzen für jedes dieser fünf Elemente angeben. Der Wert für das DefaultLocale-Element und für das Locale Attribut des Override-Elements wird gemäß RFC 3066, "Tags for the Identification of Languages" angegeben. In der folgenden Tabelle wird die Lokalisierungsunterstützung für diese Elemente beschrieben.

Element Unterstützung der Lokalisierung
Beschreibung Benutzer in allen Gebietsschemas, die Sie angeben, können eine lokalisierte Beschreibung des Add-Ins in AppSource (oder im privaten Katalog) anzeigen.
Bei Outlook-Add-Ins können Benutzer die Beschreibung nach der Installation in der Exchange-Verwaltungskonsole sehen.
DisplayName Benutzer in allen Gebietsschemas, die Sie angeben, können eine lokalisierte Beschreibung des Add-Ins in AppSource (oder im privaten Katalog) anzeigen.
Bei Outlook-Add-Ins können Benutzer nach der Installation den Anzeigenamen als Beschriftung für die Outlook-App-Schaltfläche und in der Exchange-Verwaltungskonsole sehen.
Für Inhalts- und Aufgabenbereich-Add-Ins können Benutzer den Anzeigenamen nach der Installation des Add-Ins auf dem Menüband sehen.
IconUrl Der Symbolbild ist optional. Sie können dieselbe Überschreibungstechnik verwenden, um ein bestimmtes Bild für eine bestimmte Kultur anzuzeigen. Wenn Sie ein Symbol verwenden und lokalisieren, können Benutzer in jedem Gebietsschema, das Sie angeben, ein lokalisiertes Symbolbild für das Add-In sehen.
Bei Outlook-Add-Ins können Benutzer nach der Installation das Symbol in der Exchange-Verwaltungskonsole sehen.
Für Inhalts- und Aufgabenbereich-Add-Ins können Benutzer nach der Installation des Add-Ins das Symbol auf dem Menüband sehen.
HighResolutionIconUrlWichtig: Dieses Element ist nur für das Add-In-Manifest der Version 1.1 verfügbar. Das Symbolbild mit hoher Auflösung ist optional, aber wenn es angegeben ist, muss es nach dem IconUrl-Element auftreten. Wenn HighResolutionIconUrl angegeben ist und das Add-In auf einem Gerät installiert ist, das eine hohe DPI-Auflösung unterstützt, wird der HighResolutionIconUrl-Wert anstelle des Werts für IconUrl verwendet.
Sie können dieselbe Überschreibungstechnik verwenden, um ein bestimmtes Bild für eine bestimmte Kultur anzugeben. Wenn Sie ein Symbol verwenden und lokalisieren, können Benutzer in jedem Gebietsschema, das Sie angeben, ein lokalisiertes Symbolbild für das Add-In sehen.
Bei Outlook-Add-Ins können Benutzer nach der Installation das Symbol in der Exchange-Verwaltungskonsole sehen.
Für Inhalts- und Aufgabenbereich-Add-Ins können Benutzer nach der Installation des Add-Ins das Symbol auf dem Menüband sehen.
RessourcenWichtig: Dieses Element ist nur für das Add-In-Manifest der Version 1.1 verfügbar. Benutzer in allen Gebietsschemas, die Sie angeben, können eine Zeichenfolge und Symbolressourcen anzeigen, die Sie spezifisch für das jeweilige Gebietsschema des Add-Ins erstellen.
SourceLocation Benutzer in allen Gebietsschemas, die Sie angeben, können eine Webseite anzeigen, die Sie spezifisch für das jeweilige Gebietsschema des Add-ins entwerfen.

Hinweis

Sie können die Beschreibung und den Anzeigenamen nur für die Gebietsschemas lokalisieren, die Office unterstützt. Eine Liste der Sprachen und Gebietsschemas für die aktuelle Office-Version finden Sie unter Übersicht über die Bereitstellung von Sprachen für Microsoft 365-Apps .

Beispiele

Beispielsweise kann ein Office-Add-In defaultLocale als en-usangeben. Für das DisplayName-Element kann das Add-In ein untergeordnetes Element außer Kraft setzen für das Gebietsschema fr-frangeben, wie unten gezeigt.

<DefaultLocale>en-us</DefaultLocale>
...
<DisplayName DefaultValue="Video player">
    <Override Locale="fr-fr" Value="Lecteur vidéo" />
</DisplayName>

Hinweis

Wenn Sie z. B. für mehr als einen Bereich innerhalb einer Sprachfamilie lokalisieren müssen, u. a. de-de und de-at, empfehlen wir die Verwendung von separaten Override-Elementen für jeden Bereich. Die Alleinige Verwendung des Sprachnamens , in diesem Fall , dewird nicht für alle Kombinationen von Office-Clientanwendungen und -plattformen unterstützt.

Dies bedeutet, dass das Add-In standardmäßig das en-us Gebietsschema annimmt. Benutzern wird der englische Anzeigename "Video player" für alle Gebietsschemas angezeigt, es sei denn, das Gebietsschema des Clientcomputers lautet fr-fr. In diesem Fall wird den Benutzern der französische Anzeigename "Lecteur vidéo" angezeigt.

Hinweis

Sie können nur eine Außerkraftsetzung pro Sprache angeben, einschließlich des Standardgebietsschemas. Wenn Ihr Standardgebietsschema beispielsweise ist en-us , können Sie auch keine Außerkraftsetzung für en-us angeben.

Im folgenden Beispiel wird eine Gebietsschemaüberschreibung für das Description-Element angewendet. Es gibt zuerst ein Standardgebietsschema von en-us und eine englische Beschreibung und dann eine Override-Anweisung mit einer französischen Beschreibung für das fr-fr Gebietsschema an.

<DefaultLocale>en-us</DefaultLocale>
...
<Description DefaultValue=
   "Watch YouTube videos referenced in the emails you receive
   without leaving your email client.">
   <Override Locale="fr-fr" Value=
   "Visualisez les vidéos YouTube référencées dans vos courriers 
   électronique directement depuis Outlook."/>
</Description>

Dies bedeutet, dass das Add-In standardmäßig das en-us Gebietsschema annimmt. Benutzern würde die englische Beschreibung im DefaultValue Attribut für alle Gebietsschemas angezeigt, es sei denn, das Gebietsschema des Clientcomputers lautet fr-fr. In diesem Fall würden sie die französische Beschreibung sehen.

Im folgenden Beispiel gibt das Add-In ein separates Bild an, das für das Gebietsschema und die fr-fr Kultur besser geeignet ist. Benutzern wird standardmäßig das Bild DefaultLogo.png angezeigt, außer wenn das Gebietsschema des Clientcomputers fr-fr ist. In diesem Fall wird ihnen das Bild FrenchLogo.png angezeigt.

<!-- Replace "domain" with a real web server name and path. -->
<IconUrl DefaultValue="https://<domain>/DefaultLogo.png"/>
<Override Locale="fr-fr" Value="https://<domain>/FrenchLogo.png"/>

Das folgende Beispiel zeigt, wie Sie eine Ressource im Resources Abschnitt lokalisieren. Es wird eine Gebietsschemaüberschreibung für ein Bild angewendet, das für die ja-jp Kultur besser geeignet ist.

<Resources>
      <bt:Images>
        <bt:Image id="icon1_16x16" DefaultValue="https://www.contoso.com/icon_default.png">
          <bt:Override Locale="ja-jp" Value="https://www.contoso.com/ja-jp16-icon_default.png" />
        </bt:Image>
 ...

Für das SourceLocation-Element bedeutet die Unterstützung zusätzlicher Gebietsschemas, dass für jedes der angegebenen Gebietsschemas eine separate HTML-Quelldatei bereitgestellt wird. Benutzer in allen Gebietsschemas, die Sie angeben, können eine angepasste Webseite anzeigen, die Sie für sie entwerfen.

Bei Outlook-Add-Ins wird das SourceLocation-Element ebenfalls am Formfaktor ausgerichtet. Dadurch können Sie für jede Gerätegröße eine eigene, lokalisierte HTML-Quelldatei angeben. Sie können ein oder mehrere untergeordnete Override-Elemente in jedem zutreffenden Einstellungselement (DesktopSettings, TabletSettings oder PhoneSettings) angeben. Das folgende Beispiel zeigt Einstellungselemente für die Gerätegrößen Desktop, Tablet und Smartphone mit je einer HTML-Datei für das Standardgebietsschema und einer weiteren für das Gebietsschema „Französisch".

<DesktopSettings>
   <SourceLocation DefaultValue="https://contoso.com/Desktop.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Desktop.html" />
   </SourceLocation>
   <RequestedHeight>250</RequestedHeight>
</DesktopSettings>
<TabletSettings>
   <SourceLocation DefaultValue="https://contoso.com/Tablet.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Tablet.html" />
   </SourceLocation>
   <RequestedHeight>200</RequestedHeight>
</TabletSettings>
<PhoneSettings>
   <SourceLocation DefaultValue="https://contoso.com/Mobile.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Mobile.html" />
   </SourceLocation>
</PhoneSettings>

Lokalisieren erweiterter Außerkraftsetzungen

Hinweis

Dieser Abschnitt gilt nicht, wenn Sie das einheitliche Manifest verwenden.

Wenn das Add-In ein reines Add-In-Manifest verwendet, werden einige Erweiterbarkeitsfeatures von Office-Add-Ins, z. B. Tastenkombinationen, mit JSON-Dateien konfiguriert, die auf Ihrem Server gehostet werden, anstatt mit dem XML-formatierten Manifest des Add-Ins. In diesem Abschnitt wird davon ausgegangen, dass Sie mit erweiterten Außerkraftsetzungen vertraut sind. Weitere Informationen finden Sie unter Arbeiten mit erweiterten Außerkraftsetzungen des Manifests und des ExtendedOverrides-Elements .

Verwenden Sie das ResourceUrl Attribut des ExtendedOverrides-Elements , um Office auf eine Datei lokalisierter Ressourcen zu verweisen. Es folgt ein Beispiel.

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/extended-overrides.json" 
                       ResourceUrl="https://contoso.com/addin/my-resources.json">
    </ExtendedOverrides>
</OfficeApp>

Die Datei mit erweiterten Außerkraftsetzungen verwendet dann Token anstelle von Zeichenfolgen. Die Tokennamenzeichenfolgen in der Ressourcendatei. Im folgenden Beispiel wird einer (an anderer Stelle definierten) Funktion, die den Aufgabenbereich des Add-Ins anzeigt, eine Tastenkombination zugewiesen. Beachten Sie dieses Markup:

  • Das Beispiel ist nicht ganz gültig. (Unten fügen wir eine erforderliche zusätzliche Eigenschaft hinzu.)
  • Die Token müssen das Format ${resource aufweisen.name-of-resource}.
{
    "actions": [
        {
            "id": "SHOWTASKPANE",
            "type": "ExecuteFunction",
            "name": "${resource.SHOWTASKPANE_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "${resource.SHOWTASKPANE_default_shortcut}"
            }
        }
    ] 
}

Die Ressourcendatei, die ebenfalls JSON-formatiert ist, enthält eine Eigenschaft der obersten Ebene resources , die nach Gebietsschema in Untereigenschaften unterteilt ist. Für jedes Gebietsschema wird jedem Token, das in der Datei mit erweiterten Außerkraftsetzungen verwendet wurde, eine Zeichenfolge zugewiesen. Das folgende Beispiel enthält Zeichenfolgen für en-us und fr-fr. In diesem Beispiel ist die Tastenkombination in beiden Gebietsschemas identisch, aber dies ist nicht immer der Fall, insbesondere wenn Sie Gebietsschemas lokalisieren, die ein anderes Alphabet oder Schreibsystem und damit eine andere Tastatur aufweisen.

{
    "resources":{ 
        "en-us": { 
            "SHOWTASKPANE_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "SHOWTASKPANE_action_name": {
                "value": "Show task pane for add-in",
            }, 
        },
        "fr-fr": { 
            "SHOWTASKPANE_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "SHOWTASKPANE_action_name": {
                "value": "Afficher le volet de tâche pour add-in",
              } 
        }
    }
}

Es gibt keine default Eigenschaft in der Datei, die ein Peer zu den en-us Abschnitten und fr-fr ist. Dies liegt daran, dass die Standardzeichenfolgen, die verwendet werden, wenn das Gebietsschema der Office-Hostanwendung keiner der ll-cc-Eigenschaften in der Ressourcendatei entspricht, in der Erweiterten Außerkraftsetzungsdatei selbst definiert werden müssen. Wenn Sie die Standardzeichenfolgen direkt in der Datei mit erweiterten Außerkraftsetzungen definieren, wird sichergestellt, dass Office die Ressourcendatei nicht herunter lädt, wenn das Gebietsschema der Office-Anwendung mit dem Standardgebietsschema des Add-Ins übereinstimmt (wie im Manifest angegeben). Es folgt eine korrigierte Version des vorherigen Beispiels einer datei mit erweiterten Außerkraftsetzungen, die Ressourcentoken verwendet.

{
    "actions": [
        {
            "id": "SHOWTASKPANE",
            "type": "ExecuteFunction",
            "name": "${resource.SHOWTASKPANE_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "${resource.SHOWTASKPANE_default_shortcut}"
            }
        }
    ],
    "resources": { 
        "default": { 
            "SHOWTASKPANE_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "SHOWTASKPANE_action_name": {
                "value": "Show task pane for add-in",
            } 
        }
    }
}

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 den 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 in WorldReadyAddInManifest.xml die 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 die <body>-Elementinhalte in Home.html durch die folgende HTML 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 im 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 SieNeues 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 Datei „UIStrings.js" den folgenden Code hinzu und speichern Sie die Datei.

    /* Store the locale-specific strings */

const UIStrings = (function ()
{
    "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 = function (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 Ressourcendatei „UIStrings.js" erstellt ein 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

Damit die Ressourcendatei in Ihrem Add-in verwendet werden kann, müssen Sie „Home.html" ein entsprechendes Skript-Tag hinzufügen. Wenn Home.html geladen wird, wird UIStrings.js ausgeführt, und das UIStrings-Objekt , das Sie zum Abrufen der Zeichenfolgen verwenden, ist für Ihren Code verfügbar. Fügen Sie im Kopfzeilentag für „Home.html" den folgenden HTML-Code 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 Datei „Home.js" 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" />


(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason)
    {

        $(document).ready(function () {
            // 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“.

    Abbildung 2: Sprachoptionen im Dialogfeld Word-Optionen

    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