Локализация надстроек для Office

Если надстройка предназначена для пользователей в нескольких регионах, локализация помогает обеспечить собственный интерфейс на каждом языке. Вы можете локализовать отображаемые строки, метаданные манифеста (имена, описания, значки) и даже содержимое страницы без поддержки отдельных пакетов надстроек.

Платформа надстроек Office предоставляет три взаимодополняющих подхода.

  • API JavaScript для Office. Обнаружение отображения или языкового стандарта содержимого пользователя во время выполнения и отображение правильных строк.
  • Переопределения манифеста. Объявите имена, описания, значки и исходные страницы, относящиеся к языковому стандарту, чтобы платформа автоматически выбрала правильное значение.
  • Глобализация Visual Studio/.NET. Используйте ASP.NET файлов ресурсов AJAX, JavaScript Date и расширений для форматирования на основе языка и Number региональных параметров.

В следующих разделах описаны все подходы с примерами кода.

Определение параметров, зависящих от языка, с помощью API JavaScript

API JavaScript для Office предоставляет два свойства, которые поддерживают отображение или интерпретацию значений в соответствии с языковым стандартом приложения Office и данных.

  • Context.displayLanguage указывает языковой стандарт (или язык) пользовательского интерфейса приложения Office. В следующем примере проверяется, используется ли в приложении Office языковой стандарт en-US или fr-FR, и отображается приветствие, относящееся к языковому стандарту.

    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 задает языковые параметры (или язык) данных. Расширив последний пример кода, вместо проверки свойства displayLanguage назначьте myLanguage значение свойства contentLanguage и используйте оставшуюся часть того же кода для отображения приветствия на основе языкового стандарта данных.

    const myLanguage = Office.context.contentLanguage;

Управление локализацией через манифест

Методы локализации с манифестом различаются в зависимости от того, используете ли вы только манифест надстройки или манифест унифицированного приложения для Microsoft 365.

При использовании манифеста унифицированного приложения для Microsoft 365 локализуйте общедоступные строки в манифесте, как описано в разделе Локализация строк в манифесте приложения. Ниже приведен пример надстройки Outlook. Во-первых "localizationInfo" , это объект в манифесте. Ниже приведен fr-fr.json файл с переведенными строками. Надстройка имеет область задач (с французской версией домашней страницы), локализованные французские значки и настраиваемую кнопку ленты, которая открывает видеопроигрыватель в диалоговом окне.

"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",
}

Приведение формата даты и времени к языковым параметрам клиента

Вы можете получить языковой стандарт пользовательского интерфейса клиентского приложения Office с помощью свойства displayLanguage . Затем можно отобразить значения даты и времени в формате, совместимом с текущим языковым стандартом приложения Office. Один из способов сделать это — подготовить файл ресурсов, в котором задан формат отображения даты и времени для использования с каждым из языковых параметров, поддерживаемых Надстройка Office. Во время выполнения надстройка может использовать файл ресурсов и сопоставлять соответствующий формат даты и времени с языковым параметром, полученным из свойства displayLanguage.

Вы можете получить языковой стандарт данных клиентского приложения Office с помощью свойства contentLanguage . В зависимости от этого значения можно интерпретировать или отображать строки даты и времени. Например, языковой jp-JP стандарт выражает значения даты и времени в виде yyyy/MM/dd, а языковой fr-FR стандарт — dd/MM/yyyy.

Создание локализованной и глобализированной надстройки с помощью Visual Studio

Если вы используете Visual Studio для создания надстроек Office, платформа .NET Framework и AJAX предоставляют способы глобализации и локализации файлов клиентских сценариев.

Вы можете глобализировать и использовать расширения типов JavaScript Date и Number и объект JavaScript Date в коде JavaScript для надстройки Office для отображения значений на основе параметров языкового стандарта в текущем браузере. Дополнительные сведения см. в статье Walkthrough: Globalizing a Date by Using Client Script.

Можно включить локализованные строки ресурсов напрямую в отдельные файлы JavaScript, чтобы предоставить клиентские файлы скриптов для разных языковых параметров, задаваемых в браузере или предоставляемых пользователем. Создайте отдельный файл скрипта для каждого поддерживаемого языкового параметра. В каждый файл скрипта включите объект в формате JSON, содержащий строки ресурсов для соответствующего языкового параметра. Локализованные значения применяются во время выполнения скрипта в браузере.

Пример. Создание локализованной надстройки Office

В этом разделе представлены примеры того, как локализовать описание, отображаемое имя и пользовательский интерфейс Надстройка Office.

Примечание.

Чтобы скачать Visual Studio, перейдите на страницу интегрированной среды разработки Visual Studio. Во время установки потребуется выбрать рабочую нагрузку разработки для Office и SharePoint.

Настройка Office на использование дополнительных языков для отображения или редактирования

Чтобы запустить предоставленный пример кода, настройте Office на компьютере для использования дополнительных языков, чтобы можно было протестировать надстройку, переключив язык, используемый для отображения в меню и командах, для редактирования и проверки правописания или и того, и другого.

Для установки дополнительного языка можно использовать языковой пакет Office. Дополнительные сведения о языковых пакетах и способах их получения см. на странице дополнительных языковых пакетов для Office.

После установки языкового пакета вы можете настроить Office на использование установленного языка для пользовательского интерфейса и/или для редактирования содержимого документов. В примере в этой статье используется установка Office, в которой применяется испанский языковой пакет.

Создание проекта надстройки Office

Вам потребуется создать проект надстройки Office для Visual Studio.

Примечание.

Если вы еще не установили Visual Studio, инструкции по скачиванию см. на странице интегрированной среды разработки Visual Studio . Во время установки потребуется выбрать рабочую нагрузку разработки Office и SharePoint. Если вы ранее установили Visual Studio 2019 или более поздней версии, используйте Visual Studio Installer, чтобы убедиться, что установлена рабочая нагрузка разработки Office/SharePoint.

  1. Выберите Создание нового проекта.

  2. Используя поле поиска, введите надстройка. Выберите вариант Веб-надстройка Word и нажмите кнопку Далее.

  3. Присвойте проекту имя WorldReadyAddIn и нажмите кнопку Создать.

  4. Visual Studio создаст решение, и два соответствующих проекта появятся в обозревателе решений. В Visual Studio откроется файл Home.html.

Локализация текста, используемого в вашей надстройке

Текст, который требуется локализовать для другого языка, отображается в двух областях.

  • Отображаемое имя и описание надстройки. Они управляются записями в файле манифеста приложения.

  • Пользовательский интерфейс надстройки. Вы можете локализовать строки, отображаемые в пользовательском интерфейсе надстройки, с помощью кода JavaScript, например используя отдельный файл ресурсов с локализованными строками.

Локализация отображаемого имени и описания надстройки

  1. В обозревателе решений разверните узлы WorldReadyAddIn и WorldReadyAddInManifest, а затем выберите WorldReadyAddIn.xml.

  2. В WorldReadyAddInManifest.xmlзамените элементы DisplayName и Description следующим блоком кода.

    Примечание.

    Вы можете заменить локализованные строки на испанском языке, используемые в этом примере для элементов DisplayName и Description, локализованными строками на любом другом языке.

    <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. При изменении языка интерфейса microsoft 365 с английского на испанский, например, а затем запустите надстройку, отображаемое имя и описание надстройки отображаются с локализованным текстом.

Размещение пользовательского интерфейса надстройки

  1. В обозревателе решений Visual Studio выберите элемент Home.html.

  2. Замените содержимое <body> элемента в Home.html следующим HTML-кодом и сохраните файл.

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

На следующем рисунке показан элемент заголовка (h1) и элемент абзаца (p), которые отображают локализованный текст при выполнении оставшихся шагов и запуске надстройки.

Пользовательский интерфейс надстройки с выделенными разделами заголовка и абзаца.

Добавление файла ресурсов с локализованными строками

Файл ресурсов JavaScript содержит строки, используемые для пользовательского интерфейса надстройки. HTML-код для пользовательского интерфейса примера надстройки содержит элемент <h1>, отображающий приветствие, и элемент <p>, который знакомит пользователя с надстройкой.

Чтобы включить локализованные строки для заголовка и абзаца, нужно поместить строки в отдельный файл ресурса. Файл ресурса создает объект JavaScript, который содержит отдельный объект Нотация объектов JavaScript (JSON) для каждого набора локализованных строк. Файл ресурса также предоставляет метод для получения соответствующего объекта JSON для определенного региона.

Добавление файла ресурсов в проект надстройки

  1. В Обозреватель решений в Visual Studio щелкните правой кнопкой мыши (или выберите и удерживайте) проект WorldReadyAddInWeb, а затем выберите Добавить>новый элемент.

  2. В диалоговом окне Добавление нового элемента выберите параметр файл JavaScript.

  3. Введите UIStrings.js в качестве имени файла и нажмите кнопку Добавить.

  4. Добавьте следующий код в файлUIStrings.js и сохраните файл.

    /* 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;
})();

Файл ресурсов UIStrings.js создает объект UIStrings, который содержит локализованные строки для пользовательского интерфейса надстройки.

Локализация текста, используемого для пользовательского интерфейса надстройки

Чтобы использовать файл ресурсов в надстройке, необходимо добавить для него тег скрипта на Home.html. При загрузкеHome.html выполняетсяUIStrings.js , а объект UIStrings , используемый для получения строк, становится доступным для кода. Добавьте следующий HTML-код в тег head для Home.html , чтобы сделать UIStrings доступными для кода.

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

Теперь вы можете использовать объект UIStrings, чтобы задать строки для пользовательского интерфейса надстройки.

Если вы хотите изменить локализацию надстройки в зависимости от того, какой язык используется для отображения в меню и командах в клиентском приложении Office, используйте Office.context.displayLanguage свойство , чтобы получить языковой стандарт для этого языка. Например, если язык приложения использует испанский язык для отображения в меню и командах, Office.context.displayLanguage свойство возвращает код языка es-ES.

Если вы хотите изменить локализацию надстройки в зависимости от того, какой язык используется для редактирования содержимого документа, используйте Office.context.contentLanguage свойство , чтобы получить языковой стандарт для этого языка. Например, если язык приложения использует испанский язык для редактирования содержимого Office.context.contentLanguage документа, свойство возвращает код языка es-ES.

Узнав язык, используемый приложением, можно использовать UIStrings для получения набора локализованных строк, соответствующих языку приложения.

Замените код в файлеHome.js следующим кодом. В коде показано, как изменить строки, используемые в элементах пользовательского интерфейса наHome.html , на основе языка интерфейса приложения или языка редактирования приложения.

Примечание.

Чтобы переключиться между изменением локализации надстройки на основе языка, используемого для редактирования, раскомментируйте строку кода const myLanguage = Office.context.contentLanguage; и закомментируйте строку кода. 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);
        });
    });
})();

Тестирование локализованной надстройки

Чтобы протестировать локализованную надстройку, измените язык, используемый для отображения или редактирования в приложении Office, а затем запустите надстройку.

  1. В Word выберите Файл>Параметры>Язык. На рисунке ниже показано диалоговое окно Параметры Word, открытое на вкладке языка.

    Диалоговое окно

  2. В разделе Выбор языков интерфейса выберите язык, на котором должны отображаться данные (например, испанский), а затем нажмите стрелку вверх, чтобы переместить испанский язык в начало списка. Кроме того, чтобы изменить язык, используемый для редактирования, в разделе Выберите языки редактирования выберите язык, который требуется использовать для редактирования, например испанский, а затем выберите Задать по умолчанию.

  3. Нажмите кнопку ОК, чтобы подтвердить выбор, а затем закройте Word.

  4. Нажмите клавишу F5 в Visual Studio, чтобы запустить пример надстройки, или выберите Отладка>Начать отладку в строке меню.

  5. В Word выберите Главная>Показать область задач.

После выполнения строки в пользовательском интерфейсе надстройки изменяются в соответствии с языком, используемым приложением, как показано на следующем рисунке.

Надстройка с локализованным текстом пользовательского интерфейса на испанском языке.

См. также

  • Last updated on