Share via

Localizar web parts do lado do cliente da Estrutura do SharePoint

  • Artigo

Você pode ampliar a aparência de sua Web Part de cliente do SharePoint Framework localizando-a para diferentes idiomas falados pelos usuários do SharePoint em todo o mundo. Neste artigo, você localizará uma web part na localidade holandesa (Holanda) e verificará se os valores localizados são exibidos corretamente.

Observação

Antes de seguir as etapas deste artigo, configure seu ambiente de desenvolvimento de Web Parts do lado do cliente do SharePoint.

Preparar o projeto

Criar um novo projeto

  1. Crie uma nova pasta para seu projeto.

    md react-localization

  2. Vá até a pasta do projeto.

    cd react-localization

  3. Na pasta do projeto, execute o gerador Yeoman da Estrutura do SharePoint para estruturar um novo projeto da Estrutura do SharePoint.

    yo @microsoft/sharepoint

  4. Quando solicitado, insira os seguintes valores:

    • Qual é o nome da sua solução? localização de reação
    • Que tipo de componente do cliente será criado? WebPart
    • Qual é o nome da Web Part? Saudação
    • Qual modelo você deseja usar? React

  5. Uma vez concluída a estrutura, bloqueie a versão das dependências do projeto ao executar este comando:

    npm shrinkwrap

  6. Abra a pasta do projeto no seu editor de código. Este artigo usa o Visual Studio Code nas etapas e capturas de tela, mas você pode usar o editor que preferir.

Os projetos da Estrutura do SharePoint abertos no Visual Studio Code

Substituir o código padrão

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.ts e atualize a definição da interface do IGreetingWebPartProps para o seguinte código:

    export interface IGreetingWebPartProps {
  greeting: string;
}

  2. No mesmo arquivo, altere a classe GreetingWebPart para:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {

  public render(): void {
    const element: React.ReactElement<IGreetingProps > = React.createElement(
      Greeting,
      {
        greeting: this.properties.greeting
      }
    );

    ReactDom.render(element, this.domElement);
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.DisplayGroupName,
              groupFields: [
                PropertyPaneTextField('greeting', {
                  label: strings.GreetingFieldLabel
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

  3. Atualize o componente principal React abrindo o arquivo ./src/webparts/greeting/components/Greeting.tsx e alterando seu código para:

    import * as React from 'react';
import styles from './Greeting.module.scss';
import { IGreetingProps } from './IGreetingProps';
import { escape } from '@microsoft/sp-lodash-subset';

export default class Greeting extends React.Component<IGreetingProps, {}> {
  public render(): JSX.Element {
    return (
      <div className={styles.greeting}>
        <div className={styles.container}>
          <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
            <div className="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
              <span className='ms-font-xl ms-fontColor-white'>
                Welcome to SharePoint!
              </span>
              <p className='ms-font-l ms-fontColor-white'>
                Customize SharePoint experiences using web parts.
              </p>
              <p className='ms-font-l ms-fontColor-white'>
                {escape(this.props.greeting)}
              </p>
              <a href="https://aka.ms/spfx" className={styles.button}>
                <span className={styles.label}>Learn more</span>
              </a>
            </div>
          </div>
        </div>
      </div>
    );
  }
}

  4. Atualize a interface principal do componente React abrindo o arquivo ./src/webparts/greeting/components/IGreetingProps.tsx e alterando seu código para:

    import { IGreetingWebPartProps } from '../GreetingWebPart';

export interface IGreetingProps extends IGreetingWebPartProps {
}

  5. Atualize o arquivo de definição de tipo TypeScript de localização abrindo o arquivo ./src/webparts/greeting/loc/mystrings.d.ts e alterando seu código para:

    declare interface IGreetingWebPartStrings {
  PropertyPaneDescription: string;
  DisplayGroupName: string;
  GreetingFieldLabel: string;
}

declare module 'GreetingWebPartStrings' {
  const strings: IGreetingWebPartStrings;
  export = strings;
}

  6. Atualize o arquivo de localidade de inglês americano abrindo o arquivo ./src/webparts/greeting/loc/en-us.js e alterando seu código para:

    define([], function() {
  return {
    "PropertyPaneDescription": "Greeting web part configuration",
    "DisplayGroupName": "Display",
    "GreetingFieldLabel": "Greeting to show in the web part"
  }
});

  7. No manifesto da web part, atualize o valor padrão da propriedade greeting abrindo o arquivo ./src/webparts/greeting/GreetingWebPart.manifest.json e alterando a seção properties para:

    {
  // ...
  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced" },
    "title": { "default": "Greeting" },
    "description": { "default": "Greets the user" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "greeting": "Hello"
    }
  }]
}

  8. Verifique se você aplicou todas as alterações corretamente executando o seguinte comando:

    gulp serve

  9. No SharePoint Workbench, adicione a web part à página e abra sua configuração.

    A web part Saudação adicionada à página com seu painel de propriedades aberto

Localizar o manifesto da web part

Cada Web Part do lado do cliente da Estrutura do SharePoint consiste em código e um manifesto. O manifesto fornece informações sobre a web part, como título, descrição e ícone. Ao adicionar uma web part à página, as informações do manifesto da web part são exibidas aos usuários.

Usando essas informações, os usuários decidem se a web part é a que estão procurando. Fornecer um título e uma descrição que refletem corretamente a funcionalidade da web part é essencial se você quiser que a web part seja usada. Se sua web part for usada em sites cujo idioma não é o inglês, localizar seus metadados pode melhorar ainda mais a experiência do usuário.

Algumas propriedades definidas no manifesto da web part, como título ou descrição, dão suporte a especificação de valores localizados. Para obter a lista completa de todas as propriedades de manifesto da web part que dão suporte à localização, confira Simplificar adicionando web parts com entradas pré-configuradas.

As propriedades que oferecem suporte à localização são do tipo ILocalizedString. Cada cadeia de caracteres localizada deve especificar pelo menos o valor padrão e, opcionalmente, valores de outras localidades.

Adicionar valores localizados para título, descrição e nome do grupo

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.manifest.json.
  2. Na matriz preconfiguredEntries, adicione traduções para as propriedades title, description e group em holandês (Países Baixos), alterando o código para:
{
  // ...
  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced", "nl-NL": "Anders" },
    "title": { "default": "Greeting", "nl-NL": "Begroeting" },
    "description": { "default": "Greets the user", "nl-NL": "Begroet de gebruiker" },
    "officeFabricIconFontName": "Page",
    "properties": {
      "greeting": "Hello"
    }
  }]
}

Importante

Preste atenção à ortografia correta das localidades. A primeira parte deve estar em letras minúsculas, enquanto a última precisa ser escrita em maiúsculas ("nl-NL").

  1. Execute o seguinte comando para verificar se o projeto está funcionando:

    gulp serve

Observação

Infelizmente, no momento, o SharePoint Workbench não dá suporte à visualização dos valores localizados do manifesto da web part. Ele sempre usa a tradução padrão.

Localizar o painel de propriedades da web part

Ao trabalhar com uma web part, um usuário frequentemente precisa configurá-la para suas necessidades específicas. Fornecer rótulos descritivos para os diferentes parâmetros de configuração melhora a capacidade de uso da web part e diminui o número de solicitações de suporte dos usuários em busca de ajuda na configuração das web parts.

O painel de propriedade da web part é composto por seções. Cada seção tem um cabeçalho e um ou mais controles que controlam os usuários para configurar a web part. Cada um desses controles contém um rótulo que descreve sua finalidade.

Por padrão, as Web Parts carregam as etiquetas da cadeia de caracteres de um arquivo de recurso de JavaScript. Se você criou web parts clássicas com soluções de confiança total, elas se parecerão com os arquivos de recurso .resx. Não é necessário usar esses arquivos de recurso e você pode incluir as cadeias de caracteres diretamente no código. No entanto, é altamente recomendável usar arquivos de recurso. A pequena sobrecarga adicional delas supera o esforço necessário para extrair todos os rótulos posteriormente caso você precise traduzir a Web Part no futuro.

Os arquivos de localização usados pela Web Part são armazenados na pasta ./src/webparts/greeting/loc.

Arquivos de localização usados pela Web Part do cliente do SharePoint Framework realçada no código do Visual Studio

A pasta loc contém um arquivo de definição de tipo de TypeScript (./src/webpart/greeting/loc/mystrings.d.ts) que informa ao TypeScript as diferentes cadeias de caracteres incluídas nos arquivos localizados. Usando as informações desse arquivo, seu editor de código pode fornecer IntelliSense ao trabalhar com cadeias de caracteres em código. Além disso, ao criar seu projeto, o TypeScript pode confirmar que você não está se referindo a uma cadeia de caracteres que não foi definida.

IntelliSense para cadeias de caracteres localizadas no Visual Studio Code

Para cada localidade compatível com a web part, há também um arquivo JavaScript simples (não TypeScript) com nome em letras minúsculas depois da localidade (por exemplo en-us.js) que contém as cadeias de caracteres traduzidas.

Arquivo de localização padrão estruturado com um novo projeto da Estrutura do SharePoint

Importante

Você deve prestar bastante atenção para garantir que todas as chaves especificadas no arquivo de definição de tipo TypeScript para a localização tenham traduções em todos os arquivos JavaScript de localização.

A localidade padrão usada pela Estrutura do SharePoint é en-US. Se a web part for usada em um site usando uma localidade que não dá suporte à ela, a Estrutura do SharePoint usará en-US como a localidade padrão.

Você pode substituir esse comportamento criando um arquivo de localidade denominado default.js com traduções no seu idioma de preferência. Embora o nome default.js não siga a convenção de nomenclatura de localidade, ele sinaliza para o processo de compilação da Estrutura do SharePoint para usar esse determinado arquivo de localidade como localidade de fallback em vez da localidade padrão de inglês dos EUA.

Adicionar valores localizados para as cadeias de caracteres do painel de propriedade da web part

  1. Na pasta ./src/webparts/greetings/loc, crie um novo arquivo denominado nl-nl.js e digite o seguinte código:

    define([], function() {
  return {
    "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
    "DisplayGroupName": "Weergave",
    "GreetingFieldLabel": "Begroeting die in het webonderdeel getoond wordt"
  }
});

  2. Verifique se as chaves no arquivo de definição de tipo de TypeScript para localização correspondem ao conteúdo dos arquivos de localidade para o inglês dos EUA e holandês (Países Baixos).

    O arquivo de definição de tipo de TypeScript para arquivos de localização e localidade para inglês dos EUA e holandês (Países Baixos) é aberto no código do Visual Studio lado a lado

Verificar as cadeias de caracteres do painel de propriedade da web part

Quando estiver testando as web parts usando a versão hospedada do SharePoint Workbench ou sites de equipe em um locatário de desenvolvedor, a localidade do site do contexto expressa pela propriedade spPageContextInfo.currentUICultureName será usada como a localidade padrão.

Ao testar web parts usando o SharePoint Workbench local, a Estrutura do SharePoint usa por padrão a localidade en-US para exibir cadeias de caracteres do painel de propriedade da web part. Há duas maneiras de testar os valores de outras localidades compatíveis com a sua web part.

Especificar a localidade a ser testada usando o argumento de linha de comando

Outra maneira de especificar a localidade a ser usada pelo SharePoint Workbench local é especificá-la como um argumento para a tarefa de gulp.

  • Inicie o SharePoint Workbench executando o seguinte comando:

    gulp serve --locale=nl-nl

    Mais uma vez, ao abrir a configuração da web part, você verá que todas as cadeias de caracteres do painel de propriedade estão exibidas em holandês (Países Baixos), e não no padrão inglês dos EUA.

    Cadeia de caracteres do painel de propriedade da web part em holandês (Países Baixos)

Localizar conteúdo da web part

Da mesma maneira que você localiza cadeias do painel de propriedade da web part, deverá localizar todas as cadeias de caracteres exibidas pela web part no corpo. Você pode usar a mesma abordagem que usa ao localizar as cadeias de caracteres do painel de propriedade da web part. Para cada cadeia de caracteres a ser localizada, adicione uma chave no arquivo de definição do TypeScript de localização e, em seguida, converta a cadeia de caracteres para cada uma das localidades com suporte no arquivo JavaScript de localidade correspondente.

Globalizar as cadeias de caracteres da Web Part

A web part padrão fornecida com o projeto da Estrutura do SharePoint estruturado tem suas cadeias de caracteres inseridas no código. Para que possa localizar essas cadeias de caracteres, você precisa substituí-las por referências para as cadeias de caracteres localizadas. Esse processo geralmente é conhecido como globalização ou internacionalização (ou a abreviação i18n).

  1. No editor de código, abra o arquivo ./src/webparts/greeting/components/Greetings.tsx.

  2. Na seção superior do arquivo, diretamente após a última instrução import, adicione uma referência para as cadeias de caracteres localizadas:

    import * as strings from 'GreetingWebPartStrings';

  3. Substitua o conteúdo da classe Greeting pelo seguinte código:

    // ...
export default class Greeting extends React.Component<IGreetingProps, {}> {
  public render(): JSX.Element {
    return (
      <div className={styles.greeting}>
        <div className={styles.container}>
          <div className={`ms-Grid-row ms-bgColor-themeDark ms-fontColor-white ${styles.row}`}>
            <div className="ms-Grid-col ms-u-lg10 ms-u-xl8 ms-u-xlPush2 ms-u-lgPush1">
              <span className='ms-font-xl ms-fontColor-white'>
                Welcome to SharePoint!
              </span>
              <p className='ms-font-l ms-fontColor-white'>
                Customize SharePoint experiences using web parts.
              </p>
              <p className='ms-font-l ms-fontColor-white'>
                {escape(this.props.greeting)}
              </p>
              <a href="https://aka.ms/spfx" className={styles.button}>
                <span className={styles.label}>{strings.LearnMoreButtonLabel}</span>
              </a>
            </div>
          </div>
        </div>
      </div>
    );
  }
}

Adicionar a nova cadeia de caracteres ao arquivo de definição de tipo TypeScript de localização

Depois de substituir a cadeia de caracteres por uma referência, a próxima etapa é adicionar essa cadeia de caracteres aos arquivos de localização usados pela Web Part.

  • No editor de código, abra o arquivo ./src/webparts/greetings/loc/mystrings.d.ts e altere seu código para:

    declare interface IGreetingWebPartStrings {
  PropertyPaneDescription: string;
  DisplayGroupName: string;
  GreetingFieldLabel: string;
  LearnMoreButtonLabel: string;
}

declare module 'greetingStrings' {
  const strings: IGreetingWebPartStrings;
  export = strings;
}

Adicionar valores localizados para a nova cadeia de caracteres

A última etapa será fornecer versões localizadas para a nova cadeia de caracteres em todas as localidades compatíveis com a web part.

  1. No editor de código, abra o arquivo ./src/webparts/greeting/loc/en-us.js e altere seu código para:

    define([], function() {
  return {
    "PropertyPaneDescription": "Greeting web part configuration",
    "DisplayGroupName": "Display",
    "GreetingFieldLabel": "Greeting to show in the web part",
    "LearnMoreButtonLabel": "Learn more"
  }
});

  2. Abra o arquivo ./src/webparts/greeting/loc/nl-nl.js e altere seu código para:

    define([], function() {
  return {
    "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
    "DisplayGroupName": "Weergave",
    "GreetingFieldLabel": "Begroeting die in het webonderdeel getoond wordt",
    "LearnMoreButtonLabel": "Meer informatie"
  }
});

  3. Confirme se a cadeia de caracteres traduzida é exibida corretamente ao executar o seguinte comando:

    gulp serve --locale=nl-nl

    O rótulo do botão Saiba mais exibido em holandês dos Países Baixos em vez do padrão inglês dos EUA

Melhorar a globalização e a localização de web parts usando pseudolocalidades

Usar a localização ao construir web parts proporciona vantagens claras, mas também é algo que os desenvolvedores ignoram facilmente. Muitas vezes, as traduções para outras localidades são fornecidas posteriormente no projeto e é difícil para os testadores verificarem se todo o código dará suporte corretamente a localidades diferentes.

As mesmas palavras em diferentes localidades têm comprimentos diferentes. Por exemplo, a mesma frase traduzida do inglês para o alemão ou holandês pode se tornar 35% mais longa. Sem todas as traduções disponíveis com antecedência, é difícil para os desenvolvedores e os designers garantirem que a interface do usuário poderá acomodar corretamente cadeias de caracteres mais longas.

Alguns idiomas usam caracteres especiais além do conjunto de caracteres ASCII padrão. Se os designers usarem uma fonte diferente da padrão, a fonte poderá não dar suporte corretamente a alguns caracteres especiais.

Para obter informações sobre todos esses problemas no final do projeto provavelmente levará a correções dispendiosas e atrasos. O SharePoint Framework permite que os desenvolvedores usem pseudolocalidades para solucionar esses problemas ao compilar Web Parts.

Dica

O que são pseudolocalidades? As pseudolocalidades são localidades projetadas para testar o software para o suporte apropriado nos diferentes aspectos do processo de localização, como suporte para caracteres especiais, idiomas da direita para a esquerda ou cadeias de caracteres mais longas que devem ser acomodadas na interface do usuário.

Adicionar a pseudolocalidade básica

  1. Na pasta ./src/webparts/greeting/loc, adicione um novo arquivo denominado qps-ploc.js e cole o seguinte código:

    define([], function() {
  return {
    "PropertyPaneDescription": "[!!! Gřèèƭïñϱ ωèβ ƥářƭ çôñƒïϱúřáƭïôñ ℓôřè₥ ïƥƨú !!!]",
    "DisplayGroupName": "[!!! Ðïƨƥℓᥠℓ !!!]",
    "GreetingFieldLabel": "[!!! Gřèèƭïñϱ ƭô ƨλôω ïñ ƭλè ωèβ ƥářƭ ℓôřè₥ ïƥƨú !!!]",
    "LearnMoreButtonLabel": "[!!! £èářñ ₥ôřè ℓôř !!!]"
  }
});

    Dica

    Você pode converter cadeias de caracteres em inglês dos EUA no equivalente de pseudolocalidade básica em Pseudolocalize!. Ao aumentar o comprimento da cadeia de caracteres gerada em 35%, você deverá poder simular o comprimento de cadeias de caracteres traduzidas para localidades mais longas, como alemão ou holandês. Além disso, ao envolver as traduções com colchetes e pontos de exclamação, você poderá facilmente ver se a cadeia de caracteres inteira será exibida na tela.

  2. Teste o projeto usando a pseudolocalidade básica executando o comando a seguir:

    gulp serve --locale=qps-ploc

    Depois de adicionar a web part à página, você poderá ver rapidamente que há duas cadeias de caracteres no corpo da web part que não foram internacionalizadas e ainda são exibidas em inglês dos EUA em vez de na pseudolocalidade básica.

    Duas cadeias de caracteres no corpo da web part exibidas em inglês dos EUA, apesar do teste usando a pseudolocalidade básica

  3. Abra o painel de propriedade da web part e confirme se todas as cadeias de caracteres e seus caracteres especiais são exibidos adequadamente e se eles cabem no espaço disponível corretamente.

    Painel de propriedade da web part aberto ao testar a web part no Workbench local usando a pseudolocalidade básica

Localizar valores de configurações da web part

O SharePoint dá suporte à MUI (Interface de Usuário Multilíngue), onde o administrador do site pode habilitar vários idiomas para a interface do usuário. Quando o usuário visita o site, sua interface de usuário é automaticamente exibida usando o idioma preferido com base nas preferências do usuário.

As web parts usadas em sites multilíngues devem detectar automaticamente o idioma usado atualmente e exibir seu conteúdo nesse idioma. A Estrutura do SharePoint simplifica esse processo carregando automaticamente o arquivo de recurso correspondente para o idioma usado atualmente. Além disso, ao testar as web parts da Estrutura do SharePoint usando a versão hospedada do SharePoint Workbench, este também usa automaticamente o idioma preferido pelo usuário.

Os valores configurados por meio das propriedades de web part não são armazenados em arquivos de recurso. Por padrão, o valor configurado é usado no estado em que se encontra, o que pode levar a inconsistências, como saudação do usuário em inglês quando o idioma preferido dele é holandês.

Mensagem de saudação exibida em inglês dos EUA apesar de o Workbench estar sendo definido para usar holandês (Países Baixos)

Ao usar os blocos de construção fornecidos com a Estrutura do SharePoint, você pode estender sua web part com suporte para armazenar valores de configuração da web part em vários idiomas. Para cada um dos idiomas com suporte, o painel de propriedade exibe um campo de texto separado no qual o usuário pode inserir o valor traduzido para essa propriedade.

Vários campos de texto renderizados no painel de propriedade da web part para permitir a tradução dos valores da web part

Observação

O site do SharePoint usado para testar a Web Part mostrada neste artigo é um site multilíngue com os idiomas inglês dos EUA, holandês e alemão habilitados. Para saber mais sobre como habilitar idiomas adicionais nos sites do SharePoint, confira Selecionar os idiomas que você deseja disponibilizar para a interface de usuário do site.

Adicionar a lista de idiomas suportados pelo SharePoint Online

A lista de idiomas habilitados em um site multilíngue do SharePoint é retornada como uma matriz de LCID (identificadores de localidade), por exemplo, 1033 para inglês (EUA).

No entanto, o idioma usado no momento é retornado como uma cadeia de caracteres. por exemplo, en-US para inglês (EUA). Como o JavaScript não tem uma forma nativa de converter o número LCID no nome da localidade, e vice-versa, você precisará fazer isso.

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.ts.

  2. Adicione uma nova variável de classe chamada locales dentro da GreetingWebPart existente com o seguinte código:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  private locales = {
    1025: 'ar-SA',
    1026: 'bg-BG',
    1027: 'ca-ES',
    1028: 'zh-TW',
    1029: 'cs-CZ',
    1030: 'da-DK',
    1031: 'de-DE',
    1032: 'el-GR',
    1033: 'en-US',
    1035: 'fi-FI',
    1036: 'fr-FR',
    1037: 'he-IL',
    1038: 'hu-HU',
    1040: 'it-IT',
    1041: 'ja-JP',
    1042: 'ko-KR',
    1043: 'nl-NL',
    1044: 'nb-NO',
    1045: 'pl-PL',
    1046: 'pt-BR',
    1048: 'ro-RO',
    1049: 'ru-RU',
    1050: 'hr-HR',
    1051: 'sk-SK',
    1053: 'sv-SE',
    1054: 'th-TH',
    1055: 'tr-TR',
    1057: 'id-ID',
    1058: 'uk-UA',
    1060: 'sl-SI',
    1061: 'et-EE',
    1062: 'lv-LV',
    1063: 'lt-LT',
    1066: 'vi-VN',
    1068: 'az-Latn-AZ',
    1069: 'eu-ES',
    1071: 'mk-MK',
    1081: 'hi-IN',
    1086: 'ms-MY',
    1087: 'kk-KZ',
    1106: 'cy-GB',
    1110: 'gl-ES',
    1164: 'prs-AF',
    2052: 'zh-CN',
    2070: 'pt-PT',
    2108: 'ga-IE',
    3082: 'es-ES',
    5146: 'bs-Latn-BA',
    9242: 'sr-Latn-RS',
    10266: 'sr-Cyrl-RS',
  };

  // ...
}

    A variável locales lista todos os idiomas suportados pelo SharePoint Online.

  3. Adicione dois métodos de classe que permitam que você obtenha o LCID do nome da localidade e o nome da localidade do LCID:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...

  private getLocaleId(localeName: string): number {
    const pos: number = (Object as any).values(this.locales).indexOf(localeName);
    if (pos > -1) {
      return parseInt(Object.keys(this.locales)[pos]);
    }
    else {
      return 0;
    }
  }

  private getLocaleName(localeId: number): string {
    const pos: number = Object.keys(this.locales).indexOf(localeId.toString());
    if (pos > -1) {
      return (Object as any).values(this.locales)[pos];
    }
    else {
      return '';
    }
  }
}

Remover a propriedade de web part de saudação padrão

Originalmente, a Web Part de saudação tinha a propriedade saudação definida onde o usuário poderia especificar a saudação a ser exibida na tela. A fim de adaptar a web part para dar suporte a sites multilíngues do SharePoint, você precisa armazenar valores múltiplos, um para cada idioma. Como você não pode saber antecipadamente quais idiomas serão habilitados no site, em vez de usar uma propriedade de web part estática, é possível gerar dinamicamente propriedades de web part em tempo de execução.

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.manifest.json.

  2. Remova a propriedade greeting da propriedade properties:

    {
  // ...

  "preconfiguredEntries": [{
    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Advanced
    "group": { "default": "Advanced", "nl-NL": "Anders" },
    "title": { "default": "Greeting", "nl-NL": "Begroeting" },
    "description": { "default": "Greets the user", "nl-NL": "Begroet de gebruiker" },
    "officeFabricIconFontName": "Page",
    "properties": {
    }
  }]
}

  3. Abra o arquivo ./src/webparts/greeting/GreetingWebPart.ts.

  4. Remova a propriedade greeting da definição de interface IGreetingWebPartProps:

    export interface IGreetingWebPartProps {
}

  5. Como o componente principal React deve exibir uma saudação, abra o arquivo ./src/webparts/greeting/components/IGreetingProps.ts e altere a interface IGreetingProps para:

    export interface IGreetingProps {
  greeting: string;
}

    Com essa modificação, você pode passar a saudação para ser exibida da Web Part para o componente React.

Exibir campos de texto do painel de propriedade para todos os idiomas habilitados

Anteriormente, ao usar a configuração de web part, o usuário podia configurar uma mensagem de boas-vindas. A web part permitia ao usuário configurar um único valor que era exibido a todos os usuários, independentemente de sua preferência de idioma. Ao recuperar a lista de idiomas habilitados no site atual, você pode exibir dinamicamente os campos de texto para permitir que o usuário forneça traduções para todos os idiomas habilitados no site.

Carregar as informações sobre os idiomas habilitados no site atual

A primeira etapa é carregar as informações sobre todos os idiomas habilitados no site atual.

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.ts.

  2. Adicione uma nova variável de classe chamada supportedLanguageIds:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...
  private supportedLanguageIds: number[];
  // ...
}

    Como consultaremos dados no SharePoint, usamos o Cliente Http do SharePoint nas operações.

  3. Adicione as seguintes importações logo acima de GreetingWebPart.

    import {
  SPHttpClient,
  SPHttpClientResponse
} from '@microsoft/sp-http';

  4. Na classe GreetingWebPart, adicione um novo método denominado getSupportedLanguageIds:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...

  private getSupportedLanguageIds(): Promise<number[]> {
    return new Promise<number[]>((resolve: (supportedLanguageIds: number[]) => void, reject: (error: any) => void): void => {
      if (this.supportedLanguageIds) {
        resolve(this.supportedLanguageIds);
        return;
      }

      this.context.spHttpClient.get(this.context.pageContext.web.absoluteUrl + '/_api/web?$select=SupportedUILanguageIds', SPHttpClient.configurations.v1)
      .then((response: SPHttpClientResponse): Promise<{ SupportedUILanguageIds: number[] }> => {
        return response.json();
      }).then((siteInfo: { SupportedUILanguageIds: number[] }): void => {
        this.supportedLanguageIds = siteInfo.SupportedUILanguageIds;
        resolve(siteInfo.SupportedUILanguageIds);
      }, (error: any): void => {
        reject(error);
      });
    });
  }
}

A lista de idiomas habilitados no site atual deve ser carregada apenas uma vez. Se as informações sobre os idiomas ainda não tiverem sido carregadas, o método usará o Cliente HTTP padrão da Estrutura do SharePoint para chamar a API REST do SharePoint e recuperar as informações sobre os idiomas habilitados no site atual.

Renderizar dinamicamente os campos de texto para todos os idiomas

Agora que você pode recuperar as informações sobre os idiomas habilitados no site atual, você exibirá os campos de texto para cada um desses idiomas para que o usuário possa especificar os valores traduzidos para a mensagem de saudação.

  1. No editor de código, abra o arquivo ./src/webparts/greeting/GreetingWebPart.ts.

  2. Adicione uma nova variável de classe chamada greetingFields à classe GreetingWebPart:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...
  private greetingFields: IPropertyPaneField<any>[] = [];
  // ...
}

  3. Altere a instrução import do pacote @microsoft/sp-webpart-base para:

    import {
  BaseClientSideWebPart,
  IPropertyPaneConfiguration,
  PropertyPaneTextField,
  IPropertyPaneField
} from '@microsoft/sp-webpart-base';

  4. Altere o getter propertyPaneSettings para obter a lista de campos de texto da variável de classe greetingFields adicionada recentemente:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...

    protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: {
            description: strings.PropertyPaneDescription
          },
          groups: [
            {
              groupName: strings.GreetingGroupName,
              groupFields: this.greetingFields
            }
          ]
        }
      ]
    };
  }

  // ...
}

    Se o site tiver vários idiomas habilitados, a web part processará vários campos para o usuário inserir a mensagem de saudação. Para deixar claro que esses campos devem ficar juntos, coloque-os em um grupo separado.

  5. No editor de código, abra o arquivo ./src/webparts/greeting/loc/mystrings.d.ts e altere seu código para:

    declare interface IGreetingWebPartStrings {
  PropertyPaneDescription: string;
  GreetingGroupName: string;
  LearnMoreButtonLabel: string;
}

declare module 'GreetingWebPartStrings' {
  const strings: IGreetingWebPartStrings;
  export = strings;
}

  6. Atualize os arquivos de recurso a seguir para fornecer valores para a cadeia de caracteres GreetingGroupName.

    ./src/webparts/greeting/loc/en-us.js

    define([], function() {
  return {
    "PropertyPaneDescription": "Greeting web part configuration",
    "GreetingGroupName": "Greeting to show in the web part",
    "LearnMoreButtonLabel": "Learn more"
  }
});

    ./src/webparts/greeting/loc/nl-nl.js

    define([], function() {
  return {
    "PropertyPaneDescription": "Instellingen van het begroeting webonderdeel",
    "GreetingGroupName": "Begroeting die in het webonderdeel getoond wordt",
    "LearnMoreButtonLabel": "Meer informatie"
  }
});

    ./src/webparts/greeting/loc/qps-ploc.js

    define([], function() {
  return {
    "PropertyPaneDescription": "[!!! Gřèèƭïñϱ ωèβ ƥářƭ çôñƒïϱúřáƭïôñ ℓôřè₥ ïƥƨú !!!]",
    "GreetingGroupName": "[!!! Gřèèƭïñϱ ƭô ƨλôω ïñ ƭλè ωèβ ƥářƭ ℓôřè₥ ïƥƨú !!!]",
    "LearnMoreButtonLabel": "[!!! £èářñ ₥ôřè ℓôř !!!]"
  }
});

  7. No arquivo ./src/webparts/greeting/GreetingWebPart.ts, substitua o método onPropertyPaneConfigurationStart usando o seguinte código:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...
  protected onPropertyPaneConfigurationStart(): void {
    this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'languages');

    this.getSupportedLanguageIds()
      .then((supportedLanguageIds: number[]): void => {
        this.greetingFields = [];
        supportedLanguageIds.forEach(localeId => {
          this.greetingFields.push(PropertyPaneTextField(`greeting_${localeId}`, {
            label: this.getLocaleName(localeId)
          }));
        });

        this.context.propertyPane.refresh();
        this.context.statusRenderer.clearLoadingIndicator(this.domElement);
        this.render();
      });
  }
}

    Quando o usuário abre o painel de propriedade da web part, o método carrega as informações sobre os idiomas habilitados no site atual. Como carregar essas informações pode demorar um pouco, o método exibe um indicador de carregamento comunicando seu status para o usuário.

    Depois que as informações sobre os idiomas habilitados são carregadas, o método cria um novo campo de texto do painel de propriedade vinculado a uma propriedade de web part dinâmica chamada greeting__lcid_, por exemplo, greeting_1033 para inglês (EUA).

    Depois que os campos de texto para todos os idiomas habilitados são construídos, o método atualiza o painel de propriedade chamando o método IPropertyPaneAccessor.refresh.

    Por fim, o método limpa a web part carregando o indicador e renderizando novamente o corpo da web part.

    Campos de texto para todos os idiomas exibidos no painel de propriedades da Web Part

Mostrar a saudação para o idioma preferencial do usuário

Originalmente, a web part mostrou a mesma saudação para todos os usuários, independentemente de seu idioma preferencial. Agora que a web part tem armazenada as diferentes traduções da mensagem de boas-vindas, ela deverá exibir a saudação que usa o idioma preferido pelo usuário atual.

  1. No arquivo ./src/webparts/greeting/GreetingWebPart.ts, altere o método render da web part para:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...

  public render(): void {
    const element: React.ReactElement<IGreetingProps> = React.createElement(Greeting, {
      greeting: this.getGreeting()
    });

    ReactDom.render(element, this.domElement);
  }
}

  2. Em GreetingWebPart, adicione um novo método denominado getGreeting:

    export default class GreetingWebPart extends BaseClientSideWebPart<IGreetingWebPartProps> {
  // ...

  private getGreeting(): string {
    let localeId: number = this.getLocaleId(this.context.pageContext.cultureInfo.currentUICultureName);
    if (localeId === 0) {
      localeId = 1033;
    }

    return this.properties[`greeting_${localeId}`];
  }

  // ...
}

    Esse método obtém o idioma usado no momento e o converte em uma ID de localidade. Em seguida, ele retorna o valor da propriedade de saudação traduzida para esse idioma.

Localização em tipos de compilação diferentes

Dependendo do modo de compilação selecionado, a Estrutura do SharePoint gerencia os arquivos de localização de maneira diferente. Veja algumas das diferenças entre os arquivos gerados em uma compilação de depuração e uma compilação de lançamento.

Arquivos de localização na compilação de depuração

Ao criar projetos da Estrutura do SharePoint no modo de depuração, apenas as informações sobre a localidade padrão estarão incluídas no manifesto da Web Part gerado. No modo de depuração, a Estrutura do SharePoint usa a localidade en-US padrão, ou a localidade que tenha sido especificada na configuração do projeto ou usando o argumento locale na linha de comando.

Os arquivos de recurso com cadeias de caracteres traduzidas não estão incluídos na pasta de saída dist. Em vez disso, eles são carregados em tempo de execução da pasta intermediária lib, usando o caminho no manifesto da web part gerado.

Examinando as informações sobre o módulo GreetingWebPartStrings no manifesto da web part gerado durante uma compilação de depuração, você poderá ver que, apesar das localidades diferentes compatíveis com a web part (en-US, nl-NL e qps-ploc), o caminho para o arquivo de recurso en-US armazenado no local intermediário foi designado como o caminho padrão do módulo de localização.

{
  "id": "edbc4e31-6085-4ffa-85f4-eeffcb0ea2d4",
  "alias": "GreetingWebPart",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,
  // ...
  "loaderConfig": {
    "entryModuleId": "greeting-web-part",
    "internalModuleBaseUrls": [
      "https://localhost:4321/"
    ],
    "scriptResources": {
      "greeting-web-part": {
        "type": "path",
        "path": "dist/greeting-web-part.js"
      },
      "GreetingWebPartStrings": {
        "defaultPath": "lib/webparts/greeting/loc/en-us.js",
        "type": "localizedPath",
        "paths": {
          "en-US": "lib/webparts/greeting/loc/en-us.js",
          "nl-NL": "lib/webparts/greeting/loc/nl-nl.js",
          "qps-ploc": "lib/webparts/greeting/loc/qps-ploc.js"
        }
      },
      // ...
    }
  }
}

Arquivos de localização na compilação de lançamento

Ao criar projetos da Estrutura do SharePoint no modo de versão, as informações sobre as localidades padrão estarão incluídas no manifesto da Web Part gerado. Além disso, os recursos para cada localidade são armazenados em um arquivo separado. Esses arquivos de recurso são copiados com o manifesto da web part e o pacote da web part para a pasta ./temp/deploy.

Importante

Nas compilações de lançamento, os arquivos de recurso são copiados apenas para a pasta ./temp/deploy, e não para a pasta ./dist. Ao implantar a web part no ambiente de produção, você sempre deve usar arquivos da pasta ./temp/deploy para garantir que esteja implantando todos os arquivos necessários para a web part.

Examinando o manifesto de Web Part mais recente gerado em uma compilação de versão, agora você poderá ver que o módulo GreetingWebPartStrings contém referências a todos os idiomas com suporte.

{
  "id": "edbc4e31-6085-4ffa-85f4-eeffcb0ea2d4",
  "alias": "GreetingWebPart",
  "componentType": "WebPart",
  "version": "0.0.1",
  "manifestVersion": 2,
  // ...
  "loaderConfig": {
    "entryModuleId": "greeting-web-part",
    "internalModuleBaseUrls": [
      "https://cdn.contoso.com/"
    ],
    "scriptResources": {
      "greeting-web-part": {
        "type": "path",
        "path": "greeting-web-part_159d9eb591c6716cae6d0ff15b78a19a.js"
      },
      "GreetingWebPartStrings": {
        "defaultPath": "react-localization-greetingwebpartstrings_en-us_b5e89eba6e8d819bf1647b3ab505dae5.js",
        "type": "localizedPath",
        "paths": {
          "en-US": "react-localization-greetingwebpartstrings_en-us_b5e89eba6e8d819bf1647b3ab505dae5.js",
          "nl-NL": "react-localization-greetingwebpartstrings_nl-nl_d6e80ff75385975e7737774e0802641e.js",
          "qps-ploc": "react-localization-greetingwebpartstrings_qps-ploc_effe5ee4af9cadee91bbf84327eb7308.js"
        }
      },
      // ...
    }
  }
}

Ao carregar a web part na página, a Estrutura do SharePoint carrega automaticamente o arquivo de recurso para a localidade correspondente usando as informações do site do contexto. Se nenhum arquivo de recurso correspondente for encontrado, a Estrutura do SharePoint carregará o arquivo especificado na propriedade defaultPath.

Ao manter os arquivos de recurso separados, a Estrutura do SharePoint minimiza a quantidade de dados carregada na página para a localidade que corresponde à usada no site.

Confira também