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

Вы можете реализовать любую схему локализации, которая подходит вашему Надстройка Office. API JavaScript и схема манифеста платформы Надстройки Office предоставляют несколько вариантов. API JavaScript для Office можно использовать для определения языкового стандарта и отображения строк на основе языкового стандарта приложения Office, а также для интерпретации или отображения данных на основе языкового стандарта данных. Вы можете использовать манифест, чтобы указать расположение файла надстройки и описательной информации, зависящих от языковых параметров. Кроме того, для поддержки глобализации и локализации можно использовать Visual Studio и скрипт Microsoft Ajax.

Определение параметров, зависящих от языка, с помощью 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, который поддерживается только в Outlook.

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

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

<!-- 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"/>

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

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

"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, такие как сочетания клавиш, настраиваются с помощью JSON-файлов, размещенных на сервере, а не с xml-манифестом надстройки. В этом разделе предполагается, что вы знакомы с расширенными переопределениями. См . статью Работа с расширенными переопределениями манифеста и элемента ExtendedOverrides .

ResourceUrl Используйте атрибут элемента ExtendedOverrides, чтобы указать Office на файл локализованных ресурсов. Ниже приведен пример.

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

Затем файл расширенных переопределений использует маркеры вместо строк. Строки имен маркеров в файле ресурсов. Ниже приведен пример, в котором назначается сочетание клавиш функции (определенной в другом месте), которая отображает область задач надстройки. Обратите внимание на эту разметку:

• Пример не совсем допустим. (Мы добавим к нему дополнительное обязательное свойство ниже.)
• Маркеры должны иметь формат ${resource.name-of-resource}.

{
    "actions": [
        {
            "id": "SHOWTASKPANE",
            "type": "ExecuteFunction",
            "name": "${resource.SHOWTASKPANE_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "${resource.SHOWTASKPANE_default_shortcut}"
            }
        }
    ] 
}

Файл ресурсов, который также имеет формат JSON, имеет свойство верхнего уровня resources , разделенное на вложенные свойства по языковому стандарту. Для каждого языкового стандарта каждому маркеру, который использовался в файле расширенных переопределений, назначается строка. Ниже приведен пример со строками для en-us и fr-fr. В этом примере сочетание клавиш одинаково в обоих языковых стандартах, но это не всегда так, особенно при локализации языковых стандартов с другим алфавитом или системой записи и, следовательно, другой клавиатурой.

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

В файле нет default свойства, которое является одноранговым en-us элементом для разделов и fr-fr . Это связано с тем, что строки по умолчанию, которые используются, когда языковой стандарт ведущего приложения Office не соответствует ни одному из свойств ll-cc в файле ресурсов, должны быть определены в самом файле расширенных переопределений. Определение строк по умолчанию непосредственно в файле расширенных переопределений гарантирует, что Office не скачивает файл ресурсов, если языковой стандарт приложения Office соответствует языковому стандарту надстройки по умолчанию (как указано в манифесте). Ниже приведена исправленная версия предыдущего примера файла расширенных переопределений, использующего маркеры ресурсов.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы использовать в надстройке файл ресурсов, вам потребуется добавить для него тег сценария в файл Home.html. При загрузке Home.html выполняется UIStrings.js, а объект UIStrings , используемый для получения строк, будет доступен коду. Добавьте следующий HTML-код в тег заголовка для 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 на основе языка интерфейса приложения или языка редактирования приложения.

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

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

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

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

   Рис. 2. Параметры языка в диалоговом окне Параметры Word

   

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

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

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

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

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

См. также

• Рекомендации по проектированию надстроек Office
• Общие сведения о развертывании языков для приложений Microsoft 365