Configurar a localização de objetos portáteis no ASP.NET Core

Por Hisham Bin Ateya e Sébastien Ros.

Este artigo descreve as etapas para usar arquivos de objeto portátil (PO) em um aplicativo ASP.NET Core com a estrutura Orchard Core .

Observação: Orchard Core não é um produto da Microsoft. A Microsoft não fornece suporte para esse recurso.

Visualizar ou descarregar amostra de código (como descarregar)

O que é um arquivo PO?

Os arquivos PO são distribuídos como arquivos de texto contendo as cadeias de caracteres traduzidas para um determinado idioma. Algumas vantagens de usar arquivos PO em vez de arquivos .resx incluem:

• Os ficheiros PO suportam a pluralização; Os ficheiros .resx não suportam pluralização.
• Os arquivos PO não são compilados como arquivos .resx . Como tal, ferramentas especializadas e etapas de construção não são necessárias.
• Os arquivos PO funcionam bem com ferramentas colaborativas de edição on-line.

Example

O seguinte arquivo PO de exemplo contém a tradução para duas cadeias de caracteres em francês, incluindo uma com sua forma plural:

fr.po

#: Pages/Index.cshtml:13
msgid "Hello world!"
msgstr "Bonjour le monde!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Este exemplo usa a seguinte sintaxe:

• #:: Um comentário que indica o contexto da cadeia de caracteres a ser traduzida. A mesma cadeia de caracteres pode ser traduzida de forma diferente, dependendo de onde está sendo usada.
• msgid: A cadeia de caracteres não traduzida.
• msgstr: A cadeia de caracteres traduzida.

Para apoio à pluralização, mais entradas podem ser definidas.

• msgid_plural: A cadeia de caracteres plural não traduzida.
• msgstr[0]: A cadeia de caracteres traduzida para o caso 0.
• msgstr[N]: A cadeia de caracteres traduzida para o caso N.

A especificação do arquivo PO pode ser encontrada aqui.

Configurando o suporte a arquivos PO no ASP.NET Core

Este exemplo é baseado em um aplicativo Web ASP.NET Core gerado a partir de um modelo de projeto do Visual Studio 2022.

Fazendo referência ao pacote

Adicione uma referência ao OrchardCore.Localization.Core pacote NuGet.

O .csproj arquivo agora contém uma linha semelhante à seguinte (o número da versão pode variar):

<PackageReference Include="OrchardCore.Localization.Core" Version="1.5.0" />

Registar o serviço

Adicione os serviços necessários a Program.cs:

builder.Services.AddPortableObjectLocalization();

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

builder.Services
    .AddRazorPages()
    .AddViewLocalization();

Adicione o seguinte código à sua Razor página de escolha. Index.cshtml é usado neste exemplo.

@page
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@{
    ViewData["Title"] = "Home";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
</div>

<p>@Localizer["Hello world!"]</p>

Uma IViewLocalizer instância é injetada e usada para traduzir o texto "Olá mundo!".

Criando um arquivo PO

Crie um arquivo chamado <culture code.po> na pasta raiz do aplicativo. Neste exemplo, o nome do arquivo é fr.po porque o idioma francês é usado:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Este arquivo armazena a cadeia de caracteres para traduzir e a cadeia de caracteres traduzida para francês. As traduções revertem para a cultura de origem, se necessário. Neste exemplo, o ficheiro fr.po é usado se a cultura solicitada for fr-FR ou fr-CA.

Testando o aplicativo

Execute seu aplicativo, o texto Hello world! é exibido.

Navegue para o URL /Index?culture=fr-FR. O texto Bonjour le monde! é exibido.

Pluralization

Os arquivos PO suportam formulários de pluralização, o que é útil quando a mesma cadeia de caracteres precisa ser traduzida de forma diferente com base em uma cardinalidade. Essa tarefa é complicada pelo fato de que cada idioma define regras personalizadas para selecionar qual string usar com base na cardinalidade.

O pacote Orchard Localization fornece uma API para invocar essas diferentes formas plurais automaticamente.

Criação de arquivos PO de pluralização

Adicione o seguinte conteúdo ao arquivo fr.po mencionado anteriormente:

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Il y a un élément."
msgstr[1] "Il y a {0} éléments."

Consulte O que é um arquivo PO? para obter uma explicação do que cada entrada neste exemplo representa.

Adicionando um idioma usando diferentes formulários de pluralização

Strings em inglês e francês foram usadas no exemplo anterior. Inglês e francês têm apenas duas formas de pluralização e compartilham as mesmas regras formais, em que a cardinalidade de um é mapeada para a primeira forma do plural. Qualquer outra cardinalidade é mapeada para a segunda forma plural.

Nem todas as línguas partilham as mesmas regras. Isto é ilustrado com a língua checa, que tem três formas plurais.

Crie o cs.po arquivo da seguinte forma e observe como a pluralização precisa de três traduções diferentes:

msgid "Hello world!"
msgstr "Ahoj světe!!"

msgid "There is one item."
msgid_plural "There are {0} items."
msgstr[0] "Existuje jedna položka."
msgstr[1] "Existují {0} položky."
msgstr[2] "Existuje {0} položek."

Para aceitar localizações em checo, adicione "cs" à lista de culturas suportadas no Configure método:

builder.Services
    .Configure<RequestLocalizationOptions>(options => options
        .AddSupportedCultures("fr", "cs")
        .AddSupportedUICultures("fr", "cs"));

Edite o Pages/Index.cshtml arquivo para renderizar cadeias de caracteres localizadas e plurais para várias cardinalidades:

<p>@Localizer.Plural(1, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(2, "There is one item.", "There are {0} items.")</p>
<p>@Localizer.Plural(5, "There is one item.", "There are {0} items.")</p>

Observação: Em um cenário do mundo real, uma variável seria usada para representar a contagem. Aqui, repetimos o mesmo código com três valores diferentes para expor um caso específico.

Ao mudar de cultura, você verá o seguinte:

Para /Index:

There is one item.
There are 2 items.
There are 5 items.

Para /Index?culture=fr:

Il y a un élément.
Il y a 2 éléments.
Il y a 5 éléments.

Para /Index?culture=cs:

Existuje jedna položka.
Existují 2 položky.
Existuje 5 položek.

Para a cultura checa, as três traduções são diferentes. As culturas francesa e inglesa compartilham a mesma construção para as últimas duas frases traduzidas.

Tarefas avançadas

Usando argumentos adicionais

O argumento no índice zero {0} sempre representa o valor da contagem. Ao invocar o Plural método, é possível adicionar argumentos adicionais e seu índice começará em um (1).

<p>@Localizer.Plural(count, "There is one item with the color {1}.", "There are {0} items. The main color is {1}.", color)</p>

Contextualizando cadeias de caracteres

Os aplicativos geralmente contêm as cadeias de caracteres a serem traduzidas em vários lugares. A mesma cadeia de caracteres pode ter uma tradução diferente em determinados locais dentro de um aplicativo (Razor visualizações ou arquivos de classe). Um arquivo PO suporta a noção de um contexto de arquivo, que pode ser usado para categorizar a cadeia de caracteres que está sendo representada. Usando um contexto de arquivo, uma cadeia de caracteres pode ser traduzida de forma diferente, dependendo do contexto do arquivo (ou da falta de um contexto de arquivo).

Os serviços de localização de PO usam o nome da classe completa ou a exibição usada ao traduzir uma cadeia de caracteres. Isso é feito definindo o valor na entrada msgctxt.

Considere uma pequena adição ao exemplo fr.po anterior. Uma Razor página localizada em Pages/Index.cshtml pode ser definida como o contexto do arquivo definindo o valor da entrada reservada msgctxt :

msgctxt "Views.Home.About"
msgid "Hello world!"
msgstr "Bonjour le monde!"

Com msgctxt configurado desta forma, a tradução de texto ocorre ao navegar para /Index?culture=fr-FR. A tradução não ocorre ao navegar para /Privacy?culture=fr-FR.

Quando nenhuma entrada específica é correspondida com um determinado contexto de arquivo, o mecanismo de fallback do Orchard Core procura um arquivo PO apropriado sem um contexto. Supondo que não haja nenhum contexto de arquivo específico definido para Pages/Privacy.cshtml, navegar para /Privacy?culture=fr-FR carrega um arquivo PO, tal como:

msgid "Hello world!"
msgstr "Bonjour le monde!"

Alterar a localização dos ficheiros PO

O local padrão dos arquivos PO pode ser alterado em Programs.cs:

services.AddPortableObjectLocalization(options => options.ResourcesPath = "Localization");

Neste exemplo, os arquivos PO são carregados da pasta Localização .

Implementando uma lógica personalizada para localizar arquivos de localização

Quando é necessária uma lógica mais complexa para localizar arquivos PO, a interface OrchardCore.Localization.PortableObject.ILocalizationFileLocationProvider pode ser implementada e registada como um serviço. Isso é útil quando os arquivos PO podem ser armazenados em locais variados ou quando os arquivos precisam ser encontrados dentro de uma hierarquia de pastas.

Usando um idioma pluralizado padrão diferente

O pacote inclui um Plural método de extensão específico para duas formas plurais. Para idiomas que exigem formas mais plurais, crie um método de extensão. Com um método de extensão, você não precisará fornecer nenhum arquivo de localização para o idioma padrão — as cadeias de caracteres originais já estão disponíveis diretamente no código.

Você pode usar a sobrecarga genérica Plural(int count, string[] pluralForms, params object[] arguments) que aceita uma matriz de traduções.