Localização

O PowerPortalsPro utiliza um sistema de localização baseado em JSON para todo o texto voltado para o usuário. Isso inclui rótulos de componentes, nomes de tabelas e colunas, nomes de visualização, mensagens de validação e strings específicas de aplicação. A pilha Blazor os lê; IStringLocalizera pilha React os lê através do useT() gancho. Ambas as pilhas consomem a MESMA forma JSON — strings criadas uma vez dentro app.en.json impulsionam ambas as pilhas (e quaisquer arquivos de recursos compartilhados, como strings derivadas tables.* de metadados do Dataverse, fluem automaticamente para ambas).

Arquivos de localização

A localização é impulsionada por arquivos JSON colocados em um localization diretório no projeto do servidor. Arquivos seguem a convenção name.{culture}.json de nomes (por exemplo, app.en.json). app.fr.json A mesma forma JSON controla tanto a pilha React (buscada em tempo de execução pelo fornecedor de localizador) quanto a pilha Blazor (lida na inicialização por IStringLocalizer).

React

No lado do React, o localizador é montado automaticamente por <PowerPortalsProProvider> — ele inclui um <DefaultLocalizerProvider> que busca o pacote do local ativo a /localizations/... partir do montado e em cada mudança de local. Envolva o provedor com um <LocaleProvider> quando você quiser um estado explícito de troca de local (detectado automaticamente pelo caminho da URL, ASP.NET cookie de cultura ou navigator.language por padrão). Strings que o usuário vê durante a breve janela antes da resolução do bundle renderizam como suas chaves brutas; O fornecedor troca as cadeias reais assim que a busca chega.

Blazor

Registre os diretórios de localização nos servidores Program.cs via AddLocalizationDirectory. O framework os lê na inicialização, e eles fazem backup de tudo IStringLocalizer / IStringLocalizer<T> resolvido via DI.

Arquivos de localização HTML

Para conteúdos mais longos, como modelos de e-mail, você pode usar arquivos HTML independentes em vez de incorporar strings HTML em JSON. O nome do arquivo codifica o caminho completo da chave de localização e a cultura, usando o formato {key-path}.{culture}.html.

Cada segmento separado por pontos do nome do arquivo mapeia para um nível na hierarquia de chaves de localização. O penúltimo segmento é o código de cultura (por exemplo, en, fr). Coloque esses arquivos nos mesmos diretórios de localização registrados em AddLocalizationDirectory.

Por exemplo, a seguinte estrutura de arquivo:

O arquivo emails.signup-confirmation.body.en.html mapeia para a chave emails.signup-confirmation.body de localização da en cultura. Isso é equivalente a ter o conteúdo HTML como um valor de string no seu arquivo JSON nesse caminho de chave.

Recupere o conteúdo usando a mesma IStringLocalizer chave correspondente ao nome do arquivo. O conteúdo HTML é retornado como uma string localizada e pode ser renderizado com ToMarkupString().

Etiquetas de Tabelas e Colunas

Nomes de exibição de tabelas e colunas, descrições e etiquetas de visualização são automaticamente resolvidos a partir dos arquivos de localização usando a convenção tables.{tableName}.label, tables.{tableName}.columns.{columnName}.label, e tables.{tableName}.views.{viewId}.label.

Nota

Por padrão, o framework carrega metadados para cada tabela no seu ambiente Dataverse. Para qualquer portal que suporte múltiplos idiomas, você deve definir LocalizeAllAvailableTables = false e registrar apenas as tabelas que você realmente usa AddTableToLocalize — carregar todas as tabelas desacelera o aquecimento inicial e preenche o cache de strings com etiquetas que você nunca exibe (um custo pago por idioma instalado). Registre todas as tabelas cujos rótulos aparecem na interface (grades, formulários, subgrades, gráficos), já que uma tabela exibida que não está localizada renderiza suas chaves brutas em vez de rótulos. account, contact, e adx_externalidentity são incluídos por padrão.

Ver Rótulos

Os rótulos da vista no seletor de grade são localizados sob tables.{tableName}.views.{viewId}.label, onde {viewId} é o GUID da visualização salva do Dataverse (sem colchetes, minúscula). Isso se aplica tanto MainGrid aos seletores quanto SubGrid aos de visualização.

Nota

Para visualizações personalizadas definidas via CustomViewDefinitions, a mesma convenção se aplica — use o GUID da visualização personalizada como chave. Se nenhum rótulo localizado for encontrado, o nome da visualização a partir dos GridViewDefinition metadados do ou Dataverse é usado como recurso B.

Ver cabeçalhos de coluna

Cabeçalhos de coluna exibidos em grades são resolvidos usando um padrão de recurso. O sistema primeiro procura um rótulo de coluna específico para visualização em tables.{tableName}.views.{viewId}.columns.{columnName}.label. Se não for encontrado, ele volta ao rótulo da coluna em nível de tabela em tables.{tableName}.columns.{columnName}.label. As dicas de ferramenta seguem o mesmo padrão usando .description em vez de .label.

Isso permite que você substitua o cabeçalho de uma coluna para uma visualização específica sem afetar seu rótulo em outras visualizações ou editores.

Nota

Para colunas de entidades vinculadas (por exemplo contact.emailaddress1, ), o nome da coluna na chave usa o formato com prefixo de alias. Se não for encontrado um rótulo específico para a visualização, o sistema constrói um rótulo a partir do nome da coluna vinculada e do rótulo da coluna pai (por exemplo, "Email (Contato Primário)").

Rótulos de Escolha (Conjunto de Opções)

Os rótulos das opções das colunas de escolha são localizados de forma diferente dependendo se o conjunto de opções é com escopo de tabela ou global.

Escolhas com escopo de tabela

Escolhas com escopo de tabela são localizadas sob tables.{tableName}.choices.{choiceLogicalName}.values.{value}.label. O nome lógico da escolha é precedido pelo nome da tabela (por exemplo, account_accountcategorycode).

Escolhas Globais

Escolhas globais (conjuntos de opções compartilhados entre múltiplas tabelas) são localizadas no nível raiz sob choices.{choiceLogicalName}.values.{value}.label, fora de qualquer seção de tabela.

Nota

Os ChoiceEdit componentes e MultiSelectChoiceEdit resolvem automaticamente as etiquetas de escolha a partir da localização correta com base na IsGlobal propriedade dos metadados da coluna.

Injeção do localizador

Existem duas maneiras de injetar o localizador de string:

• IStringLocalizer — Acesse todas as chaves de localização globalmente. Use isso para etiquetas de tabelas, strings compartilhadas ou quando precisar do GetPrefixedLocalizer método.
• IStringLocalizer<T> — Escopado para um tipo específico de componente. As chaves são resolvidas em relação ao caminho do namespace do componente no arquivo JSON (por exemplo, components.{Namespace}.{ComponentName}.{key}).

Chaves com escopo de componentes

Ao usar IStringLocalizer<T>, as chaves são resolvidas com base no namespace e no nome da classe do componente. Por exemplo, um componente em Pages.Editors.TextEdit.TextEditDemoPage resolve chaves de components.{AssemblyName}.Pages.Editors.TextEdit.TextEditDemoPage.{key} no JSON.

Localizador Prefixado

Use GetPrefixedLocalizer para criar um sub-localizador que automaticamente anteponha um prefixo a todas as buscas de chaves. Isso é útil para evitar prefixos repetitivos de teclas em componentes que usam muitas teclas da mesma seção.

HTML em Strings Localizadas

Strings localizadas podem conter marcação HTML. Use o método de ToMarkupString() extensão para renderizá-los como MarkupString nos templates do Razor.

Encontrando a Melhor Combinação

Use-se FindLocalizedString para procurar a primeira chave correspondente de uma lista de candidatos. Isso é útil para padrões de recurso, onde você quer tentar uma chave específica primeiro e depois recorrer a uma mais geral.

No lado do React, retorna useT() a chave bruta quando uma string está faltando — t(key) !== key é o teste "essa chave resolveu?" que você cria um walkback de backup. Envolva o molde em um auxiliar quando precisar em vários pontos de chamada.

Interpolação de argumentos

As cordas podem incluir posicionais {0}, {1}, ... Provisórios de posição que são substituídos no momento da consulta. Blazor passa args como um array de parâmetros para IStringLocalizer; React passa por elas como o segundo argumento para t(). Especificadores de formato opcionais dentro de um marcador de lugar ({0:N0}, {1:yyyy-MM-dd}) são respeitados apenas pelo pipeline de String.Format Blazor; para React, pré-formate com Intl.NumberFormat / Intl.DateTimeFormat antes de passar o valor em.

Carregamento Ansioso (React)

Em caso de erro no cache, a pilha React recupera preguiçosamente o bundle por recurso que possui (um lote debounced a cada ~75 ms) e re-renderiza o componente consumidor quando as strings aterrissam. Para eliminar o breve flash das chaves brutas, declare os prefixos que uma página precisará no início via useLocalization([...]), ou espere a renderização até que eles se resolvam pelo wrapper de nível <LocalizationBoundary> superior. Veja a página LocalizationBoundary para o padrão completo.