Localização para Suplementos do Office

Se o seu suplemento for destinado a usuários em várias regiões, a localização ajudará você a oferecer uma experiência nativa em cada idioma. Você pode localizar cadeias de caracteres de exibição, metadados de manifesto (nomes, descrições, ícones) e até mesmo o conteúdo da página, tudo sem manter pacotes de suplemento separados.

A plataforma de Suplementos do Office oferece três abordagens complementares.

  • API JavaScript do Office. Detecte a localidade de exibição ou conteúdo do usuário em runtime e mostre as cadeias de caracteres corretas.
  • Manifesto substituições. Declare nomes, descrições, ícones e páginas de origem específicos da localidade para que a plataforma escolha o valor correto automaticamente.
  • Globalização do Visual Studio/.NET. Use ASP.NET arquivos de recurso AJAX e o JavaScript Date e Number extensões para formatação com reconhecimento de cultura.

As seções a seguir orientam você em cada abordagem com exemplos de código.

Usar a API JavaScript para determinar cadeias de caracteres específicas da localidade

A API JavaScript do Office fornece duas propriedades que dão suporte à exibição ou interpretação de valores consistentes com a localidade do aplicativo e dos dados do Office.

  • Context.displayLanguage especifica a localidade (ou o idioma) da interface do usuário do aplicativo do Office. O exemplo a seguir verifica se o aplicativo do Office usa a localidade en-US ou fr-FR e exibe uma saudação específica da localidade.

    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 especifica a localidade (ou idioma) dos dados. Estendendo a última amostra de código, em vez de verificar a propriedade displayLanguage , atribua myLanguage o valor da propriedade contentLanguage e use o restante do mesmo código para exibir uma saudação com base na localidade dos dados.

    const myLanguage = Office.context.contentLanguage;

Controlar a localização do manifesto

As técnicas de localização com o manifesto diferem dependendo se você usa o manifesto somente do suplemento ou o manifesto de aplicativo unificado para Microsoft 365.

Ao usar o manifesto de aplicativo unificado para Microsoft 365, localize as cadeias de caracteres voltadas para o público no manifesto, conforme descrito em Localizar cadeias de caracteres no manifesto do aplicativo. Veja a seguir um exemplo de suplemento do Outlook. O primeiro é o "localizationInfo" objeto no manifesto. Abaixo disso está o arquivo fr-fr.json com as strings traduzidas. O suplemento tem um painel de tarefas (com uma versão francesa da home page), ícones franceses localizados e um botão personalizado da faixa de opções que abre um player de vídeo em uma caixa de diálogo.

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

Fazer a correspondência entre o formato de data/hora e a localidade do cliente

Você pode obter a localidade da interface do usuário do aplicativo cliente do Office usando a propriedade displayLanguage . Em seguida, você pode exibir os valores de data e hora em um formato consistente com a localidade atual do aplicativo do Office. Uma maneira de fazer isso é preparar um arquivo de recurso que especifica o formato de exibição de data/hora a ser usado em cada localidade com suporte do seu Suplemento do Office. Na execução, seu suplemento pode usar o arquivo de recurso e fazer a correspondência entre o formato de data/hora apropriado e a localidade obtida na propriedade displayLanguage

Você pode obter a localidade dos dados do aplicativo cliente do Office usando a propriedade contentLanguage . Com base nesse valor, você pode, então, interpretar ou exibir adequadamente as cadeias de caracteres de data/hora. Por exemplo, a jp-JP localidade expressa valores de data/hora como yyyy/MM/dd, e a fr-FR localidade, dd/MM/yyyy.

Usar o Visual Studio para criar um suplemento localizado e globalizado

Se você usa o Visual Studio para criar Suplementos do Office, o .NET Framework e o AJAX fornecem maneiras de globalizar e localizar arquivos de script do cliente.

Você pode globalizar e utilizar as extensões do tipo JavaScript de Data e Número e o objeto Data do JavaScript no código do JavaScript para um suplemento do Office para exibir valores com base nas configurações de localização do navegador atual. Para saber mais, confira Passo a passo: como globalizar uma data usando o script de cliente.

Você pode incluir cadeias de caracteres de recurso localizadas diretamente em arquivos de JavaScript autônomos para fornecer arquivos de script de cliente para diferentes locais, que são definidos no navegador ou fornecidos pelo usuário. Crie um arquivo de script separado para cada localidade com suporte. Em cada arquivo de script, inclua um objeto no formato JSON que contenha as cadeias de caracteres de recursos para essa localidade. Os valores localizados serão aplicados quando o script for executado no navegador.

Exemplo: Criar um Suplemento do Office localizado

Esta seção fornece exemplos que mostram como localizar uma descrição do Suplemento do Office, o nome de exibição e interface do usuário.

Observação

Para baixar o Visual Studio, consulte a página IDE do Visual Studio. Durante a instalação, você precisará selecionar a carga de trabalho de desenvolvimento do Office/SharePoint.

Configurar o Office para usar idiomas adicionais para exibição ou edição

Para executar o código de exemplo fornecido, configure o Office em seu computador para usar idiomas adicionais para que você possa testar seu suplemento alternando o idioma usado para exibição em menus e comandos, para edição e revisão de texto, ou ambos.

Você pode usar um Office Language Pack para instalar um idioma adicional. Para saber mais sobre os Pacotes de Idiomas e onde obtê-los, veja Language Accessory Pack do Office.

Depois de instalar o Language Accessory Pack, você pode configurar o Office para usar o idioma instalado para exibir na interface do usuário, para edição de conteúdo do documento ou ambos. O exemplo neste artigo usa uma instalação do Office que tenha o Pacote de Idiomas de espanhol aplicado.

Criar um projeto de Suplemento do Office

Você precisará criar um projeto de Suplemento do Office do Visual Studio.

Observação

Se você ainda não instalou o Visual Studio, consulte a página IDE do Visual Studio para obter instruções de download. Durante a instalação, você precisará selecionar a carga de trabalho de desenvolvimento do Office/SharePoint. Se você instalou anteriormente o Visual Studio 2019 ou posterior, use o Visual Studio Installer para garantir que a carga de trabalho de desenvolvimento do Office/SharePoint seja instalada.

  1. Escolha Criar um novo projeto.

  2. Usando a caixa de pesquisa, insira suplemento. Escolha Suplemento do Word Web , em seguida, selecione Próximo.

  3. Nomeie seu projeto como WorldReadyAddIn e selecione Criar.

  4. O Visual Studio cria uma solução, e os dois projetos dele aparecem no Gerenciador de Soluções. O arquivo Home.html é aberto no Visual Studio.

Localizar o texto usado no seu suplemento

O texto que você deseja localizar para outro idioma aparece em duas áreas.

  • Nome de exibição e descrição do suplemento. Isso é controlado por entradas no arquivo do manifesto do suplemento.

  • Interface do usuário do suplemento. Você pode localizar as cadeias de caracteres que aparecem na interface do usuário do seu suplemento usando códigos do JavaScript, por exemplo, usando um arquivo de recurso separado que contenha as cadeias de caracteres localizadas.

Localize o nome de exibição e a descrição do suplemento

  1. Em Gerenciador de Soluções, expanda WorldReadyAddIn, WorldReadyAddInManifest e escolha WorldReadyAddIn.xml.

  2. No WorldReadyAddInManifest.xml, substitua os elementos DisplayName e Description pelo bloco de código a seguir.

    Observação

    Você pode substituir as cadeias de caracteres do idioma espanhol localizado usadas neste exemplo dos elementos DisplayName e Description pelas cadeias de caracteres localizados para qualquer outro idioma.

    <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. Quando você altera o idioma de exibição do Microsoft 365 de inglês para espanhol, por exemplo, e executa o suplemento, o nome de exibição e a descrição do suplemento são mostrados com texto localizado.

Dispor a interface do usuário do suplemento

  1. No Visual Studio, no Gerenciador de Soluções, selecione Home.html.

  2. Substitua o conteúdo do <body> elemento no Home.html pelo HTML a seguir e salve o arquivo.

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

A figura a seguir mostra o elemento título (h1) e o elemento parágrafo (p) que exibem o texto localizado quando você conclui as etapas restantes e executa o suplemento.

A interface do usuário do suplemento com as seções de título e parágrafo realçadas.

Adicionar o arquivo de recurso que contém as cadeias de caracteres localizadas

O arquivo de recurso do JavaScript contém as cadeias de caracteres usadas para a interface do usuário do suplemento. O HTML da interface do usuário do suplemento de amostra tem um elemento <h1> que exibe uma saudação e um elemento <p> que apresenta o suplemento ao usuário.

Para habilitar cadeias de caracteres para o cabeçalho e parágrafo, coloque as cadeias de caracteres em um arquivo de recurso separado. O arquivo de recurso cria um objeto do JavaScript que contém um objeto JSON (JavaScript Object Notation) separado para cada conjunto de cadeias de caracteres localizadas. O arquivo de recurso também fornece um método para obter o objeto JSON apropriado de volta para uma determinada localidade.

Adicionar o arquivo de recurso ao projeto de suplemento

  1. No Gerenciador de Soluções no Visual Studio, clique com o botão direito do mouse (ou selecione e segure) no projeto WorldReadyAddInWeb e escolha Adicionar>Novo Item.

  2. Na caixa de diálogo Adicionar Novo Item, escolha Arquivo JavaScript.

  3. Insira UIStrings.js como nome do arquivo e escolha Adicionar.

  4. Adicione o código a seguir ao arquivo UIStrings.js e salve o arquivo.

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

O arquivo de recursoUIStrings.js cria um objeto, UIStrings, que contém as cadeias de caracteres localizadas para a interface do usuário do suplemento.

Localizar o texto usado na interface do usuário do suplemento

Para usar o arquivo de recurso no suplemento, você precisará adicionar uma marca de script para ele no Home.html. Quando Home.html é carregado, UIStrings.js é executado e o objeto UIStrings que você usa para obter as cadeias de caracteres está disponível para o seu código. Adicione o HTML a seguir na marca head do Home.html para disponibilizar UIStrings para seu código.

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

Agora você pode usar o objeto UIStrings para definir as cadeias de caracteres da interface do usuário do seu suplemento.

Se você quiser alterar a localização do seu suplemento com base no idioma usado para exibição em menus e comandos no aplicativo cliente do Office, use a Office.context.displayLanguage propriedade para obter a localidade desse idioma. Por exemplo, se o idioma do aplicativo usa espanhol para exibição em menus e comandos, a Office.context.displayLanguage propriedade retorna o código do idioma es-ES.

Se você quiser alterar a localização do seu suplemento com base no idioma que está sendo usado para editar o conteúdo do documento, use a Office.context.contentLanguage propriedade para obter a localidade desse idioma. Por exemplo, se o idioma do aplicativo usa espanhol para editar o conteúdo do documento, a Office.context.contentLanguage propriedade retorna o código do idioma es-ES.

Depois de saber o idioma que o aplicativo está usando, você pode usar UIStrings para obter o conjunto de cadeias de caracteres localizadas que correspondem ao idioma do aplicativo.

Substitua o código no arquivo Home.js pelo código a seguir. O código mostra como você pode alterar as cadeias de caracteres usadas nos elementos da interface do usuário em Home.html com base no idioma de exibição do aplicativo ou no idioma de edição do aplicativo.

Observação

Para alternar entre alterar a localização do suplemento com base no idioma usado para edição, remova o comentário da linha de código const myLanguage = Office.context.contentLanguage; e comente a linha de código 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);
        });
    });
})();

Testar seu suplemento localizado

Para testar seu suplemento localizado, altere o idioma usado para exibição ou edição no aplicativo do Office e execute seu suplemento.

  1. No Word, escolha Arquivo>Opções>Idioma. A figura a seguir mostra a caixa de diálogo Opções do Word aberta na guia Idioma.

    A caixa de diálogo Opções do Word mostrando a guia Idioma.

  2. Em Escolher Idioma de Exibição, selecione o idioma desejado para exibição, por exemplo, espanhol, e selecione a seta para cima para mover o idioma espanhol para a primeira posição na lista. Como alternativa, para alterar o idioma usado para edição, em Escolher Idiomas de Edição, escolha o idioma que deseja usar para edição, por exemplo, espanhol e, em seguida, escolha Definir como Padrão.

  3. Escolha OK para confirmar sua seleção e feche o Word.

  4. Pressione F5 no Visual Studio para executar o suplemento de amostra ou escolha Depurar>Iniciar Depuração na barra de menus.

  5. No Word, escolha Página Inicial>Mostrar Painel de Tarefas.

Depois de executadas, as cadeias de caracteres na interface do usuário do suplemento são alteradas para corresponder ao idioma usado pelo aplicativo, conforme mostrado na figura a seguir.

O suplemento mostrando o texto localizado da interface do usuário em espanhol.

Confira também

  • Last updated on