Visão geral de globalização e localização do WPF

Artigo
10/18/2023

Quando você limita a disponibilidade do seu produto a apenas um idioma, você limita sua base de clientes em potencial a uma fração da população de 7,5 bilhões de habitantes do mundo. Se desejar que seus aplicativos alcancem um público global, a localização econômica de seu produto será uma das melhores e mais econômicas maneiras de alcançar mais clientes.

Esta visão geral apresenta a globalização e a localização no Windows Presentation Foundation (WPF). A globalização é o design e o desenvolvimento de aplicativos que são executados em várias localizações. Por exemplo, a globalização dá suporte a interfaces do usuário localizadas e a dados regionais para usuários em culturas diferentes. O WPF fornece recursos de design globalizado, incluindo layout automático, montagens satélites e atributos e comentários localizados.

A localização é a tradução de recursos do aplicativo em versões localizadas para culturas específicas às quais o aplicativo dá suporte. Ao localizar no WPF, você usa as APIs no System.Windows.Markup.Localizer namespace. Essas APIs ativam a ferramenta de linha de comando Amostra da Ferramenta LocBaml. Para obter informações sobre como criar e usar o LocBaml, consulte Localizar um aplicativo.

Aviso

A ferramenta LocBaml só funciona com WPF para projetos do .NET Framework, não funciona com WPF para .NET.

Melhores práticas de globalização e localização no WPF

Você pode aproveitar ao máximo a funcionalidade de globalização e localização incorporada ao WPF seguindo as dicas relacionadas ao design da interface do usuário e à localização fornecidas nesta seção.

Melhores práticas de design de interface do usuário no WPF

Ao criar uma interface do usuário baseada em WPF, considere a implementação destas práticas recomendadas:

Escreva sua interface do usuário em XAML; evite criar a interface do usuário no código. Ao criar sua interface do usuário usando XAML, você a expõe por meio de APIs de localização internas.
Evite usar posições absolutas e tamanhos fixos para dispor o conteúdo; em vez disso, use o dimensionamento relativo ou automático.
- Use SizeToContent e mantenha larguras e alturas definidas como Auto.
- Evite usar Canvas para dispor interfaces do usuário.
- Use Grid e seu recurso de compartilhamento de tamanho.
Forneça espaço extra nas margens, pois, de modo geral, o texto localizado exige mais espaço. O espaço extra permite possíveis caracteres estendidos.
Habilite TextWrapping para TextBlock evitar o recorte.
Defina o atributo xml:lang . Esse atributo descreve a cultura de um elemento específico e seus elementos filho. O valor dessa propriedade altera o comportamento de vários recursos no WPF. Por exemplo, ele altera o comportamento de hifenização, verificação ortográfica, substituição de números, formatação de scripts complexos e fallback de fontes. Consulte Globalização do WPF para obter mais informações sobre como definir a Manipulação de xml:lang em XAML.
Crie uma fonte de composição personalizada para obter um melhor controle das fontes que são usadas para diferentes idiomas. Por padrão, o WPF usa a fonte GlobalUserInterface.composite no diretório Windows\Fonts.
Quando você cria aplicativos de navegação que podem ser localizados em uma cultura que apresenta texto em um formato da direita para a esquerda, defina explicitamente o FlowDirection de cada página para garantir que a página não herde FlowDirection do NavigationWindow.
Quando você cria aplicativos de navegação autônomos hospedados fora de um navegador, defina o StartupUri para seu aplicativo inicial como uma NavigationWindow página em vez de uma página (por exemplo, <Application StartupUri="NavigationWindow.xaml">). Esse design permite que você altere a FlowDirection janela e a barra de navegação. Para obter mais informações e um exemplo, consulte Amostra de globalização de home page.

Melhores práticas de localização no WPF

Ao localizar aplicativos baseados em WPF, considere a implementação destas práticas recomendadas:

Use comentários de localização para fornecer contexto extra para localizadores.
Use atributos de localização para controlar a localização em vez de omitir Uid seletivamente propriedades em elementos. Consulte Atributos e comentários de localização para obter mais informações.
Use msbuild -t:updateuid e para adicionar e -t:checkuid verificar Uid propriedades em seu XAML. Use Uid propriedades para controlar alterações entre desenvolvimento e localização. Uid As propriedades ajudam a localizar novas alterações de desenvolvimento. Se você adicionar Uid manualmente propriedades a uma interface do usuário, a tarefa normalmente será tediosa e menos precisa.
- Não edite ou altere Uid propriedades depois de iniciar a localização.
- Não use propriedades duplicadas Uid (lembre-se desta dica ao usar o comando copiar e colar).
- Defina o local em AssemblyInfo.* para especificar o UltimateResourceFallback idioma apropriado para fallback (por exemplo, [assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)]).
  
  Se você decidir incluir o idioma de origem no assembly principal omitindo a <UICulture> tag no arquivo de projeto, defina o local como o UltimateResourceFallback assembly principal em vez do satélite (por exemplo, [assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.MainAssembly)]).

Localizar um aplicativo WPF

Quando você localiza um aplicativo WPF, você tem várias opções. Por exemplo, você pode vincular os recursos localizáveis em seu aplicativo a um arquivo XML, armazenar texto localizável em tabelas resx ou fazer com que seu localizador use arquivos XAML. Esta seção descreve um fluxo de trabalho de localização que usa o formulário BAML de XAML, que fornece vários benefícios:

Você pode localizar depois de compilar.
Você pode atualizar para uma versão mais recente do formulário BAML de XAML com localizações de uma versão mais antiga do formulário BAML de XAML para que você possa localizar ao mesmo tempo que desenvolve.
Você pode validar os elementos de origem originais e a semântica em tempo de compilação porque a forma BAML de XAML é a forma compilada de XAML.

Processo de build para localização

Quando você desenvolve um aplicativo WPF, o processo de compilação para localização é o seguinte:

O desenvolvedor cria e globaliza o aplicativo do WPF. No arquivo de projeto, o desenvolvedor define <UICulture>en-US</UICulture> para que, quando o aplicativo for compilado, um assembly principal com neutralidade de idioma seja gerado. Esse assembly tem um arquivo satélite .resources.dll que contém todos os recursos localizáveis. Opcionalmente, você pode manter o idioma de origem no assembly principal porque nossas APIs de localização oferecem suporte à extração do assembly principal.
Quando o arquivo é compilado na compilação, o XAML é convertido para o formulário BAML de XAML. Os arquivos culturalmente neutros MyDialog.exe e culturalmente dependentes (em inglês) MyDialog.resources.dll são liberados para o cliente que fala inglês.

Fluxo de trabalho de localização

O processo de localização começa depois que o arquivo não localizado MyDialog.resources.dll é criado. Os elementos e propriedades da interface do usuário em seu XAML original são extraídos da forma BAML de XAML em pares chave-valor usando as APIs em System.Windows.Markup.Localizer. Os localizadores usam os pares chave-valor para localizar o aplicativo. É possível gerar um novo .resource.dll com base nos novos valores após a conclusão da localização.

As chaves dos pares chave-valor são x:Uid valores colocados pelo desenvolvedor no XAML original. Esses x:Uid valores permitem que a API rastreie e mescle alterações que ocorrem entre o desenvolvedor e o localizador durante a localização. Por exemplo, se o desenvolvedor alterar a interface do usuário depois que o localizador começar a localizar, você poderá mesclar a alteração de desenvolvimento com o trabalho de localização já concluído para que o trabalho mínimo de tradução seja perdido.

O gráfico a seguir mostra um fluxo de trabalho típico de localização que se baseia no formato BAML de XAML. Este diagrama pressupõe que o desenvolvedor escreva o aplicativo em inglês. O desenvolvedor cria e globaliza o aplicativo do WPF. No arquivo de projeto, o desenvolvedor define <UICulture>en-US</UICulture> para que, na compilação, um assembly principal de linguagem neutra seja gerado com um .resources satélite.dll contendo todos os recursos localizáveis. Como alternativa, é possível manter o idioma de origem no assembly principal, pois as APIs de localização do WPF dão suporte à extração do assembly principal. Após o processo de build, o XAML é compilado para o BAML. O MyDialog.exe.resources.dll com neutralidade de cultura é enviado para o cliente falante de inglês.

Diagram showing the Localization workflow.

Diagram showing the Unlocalized workflow.

Exemplos de localização no WPF

Esta seção contém exemplos de aplicativos localizados para ajudá-lo a entender como criar e localizar aplicativos WPF.

Exemplo da caixa de diálogo Executar

Os gráficos a seguir mostram a saída da amostra da caixa de diálogo Executar.

Inglês:

Screenshot showing an English Run dialog box.

Alemão:

Screenshot showing a German Run dialog box.

Criando uma caixa de diálogo Executar global

Este exemplo produz uma caixa de diálogo Executar usando WPF e XAML. Essa caixa de diálogo é equivalente à caixa de diálogo Executar que está disponível no menu Iniciar do Microsoft Windows.

Alguns destaques para a criação de caixas de diálogo globais são:

Layout automático

Em Window1.xaml:

<Window SizeToContent="WidthAndHeight">

A propriedade Window anterior redimensiona automaticamente a janela de acordo com o tamanho do conteúdo. Essa propriedade impede que a janela corte o conteúdo que aumenta de tamanho após a localização; ela também remove o espaço desnecessário quando o conteúdo diminui de tamanho após a localização.

<Grid x:Uid="Grid_1">

Uid propriedades são necessárias para que as APIs de localização do WPF funcionem corretamente.

Eles são usados pelas APIs de localização do WPF para controlar as alterações entre o desenvolvimento e a localização da interface do usuário (UI). Uid propriedades permitem mesclar uma versão mais recente da interface do usuário com uma localização mais antiga da interface do usuário. Você adiciona uma Uid propriedade executando msbuild -t:updateuid RunDialog.csproj em um shell de comando. Esse é o método recomendado para adicionar Uid propriedades porque adicioná-las manualmente normalmente é demorado e menos preciso. Você pode verificar se Uid as propriedades estão definidas corretamente executando msbuild -t:checkuid RunDialog.csprojo .

A interface do usuário é estruturada usando o controle, que é um controle útil para aproveitar o Grid layout automático no WPF. Observe que a caixa de diálogo é dividida em três linhas e cinco colunas. Nenhuma das definições de linha e coluna tem um tamanho fixo; portanto, os elementos da interface do usuário posicionados em cada célula podem se adaptar a aumentos e diminuições de tamanho durante a localização.

<Grid.ColumnDefinitions>
  <ColumnDefinition x:Uid="ColumnDefinition_1" />
  <ColumnDefinition x:Uid="ColumnDefinition_2" />

As duas primeiras colunas em que o rótulo Abrir: e ComboBox são colocados usam 10% da largura total da interface do usuário.

  <ColumnDefinition x:Uid="ColumnDefinition_3" SharedSizeGroup="Buttons" />
  <ColumnDefinition x:Uid="ColumnDefinition_4" SharedSizeGroup="Buttons" />
  <ColumnDefinition x:Uid="ColumnDefinition_5" SharedSizeGroup="Buttons" />
</Grid.ColumnDefinitions>

Observe que o exemplo usa o recurso de dimensionamento compartilhado do Grid. As três últimas colunas aproveitam isso colocando-se no mesmo SharedSizeGroup. Como normalmente se esperaria do nome da propriedade, isso permite que as colunas compartilhem o mesmo tamanho. Então, quando o "Procurar..." fica localizado para a string mais longa "Durchsuchen...", todos os botões crescem em largura em vez de ter um pequeno botão "OK" e um "Durchsuchen..." botão.

xml:lang

xml:lang="en-US"

Observe o xml:lang Handling em XAML colocado no elemento raiz da interface do usuário. Essa propriedade descreve a cultura de determinado elemento e seus filhos. Esse valor é usado por vários recursos no WPF e deve ser alterado adequadamente durante a localização. Esse valor altera qual dicionário de idioma deve ser usado para hifenizar e fazer a verificação ortográfica das palavras. Ele também afeta a exibição de dígitos e como o sistema de fallback de fontes seleciona qual fonte deve ser usada. Finalmente, a propriedade afeta a maneira como os números são exibidos e o modo como os textos escritos em scripts complexos são formatados. O valor padrão é “en-US”.

Compilando um assembly de recursos satélite

Em .csproj:

Edite o .csproj arquivo e adicione a seguinte marca a um incondicional <PropertyGroup>:

<UICulture>en-US</UICulture>

Observe a adição de um UICulture valor. Quando isso é definido como um valor válido CultureInfo , como en-US, a criação do projeto gerará um assembly satélite com todos os recursos localizáveis nele.

<Resource Include="RunIcon.JPG">

<Localizable>False</Localizable>

</Resource>

O RunIcon.JPG não precisa ser localizado porque deve parecer o mesmo para todas as culturas. Localizable é definido para false que ele permaneça no assembly principal de idioma neutro em vez do assembly satélite. O valor padrão de todos os recursos não compiláveis é Localizable definido como true.

Localizando a caixa de diálogo Executar

Analisar

Depois de criar o aplicativo, a primeira etapa da localização é analisar os recursos localizáveis fora do assembly satélite. Para as finalidades deste tópico, use a ferramenta LocBaml de exemplo, que pode ser encontrada em Amostra da Ferramenta LocBaml. Observe que LocBaml é apenas uma ferramenta de exemplo para ajudá-lo a começar a criar uma ferramenta de localização que se ajuste ao seu processo de localização. Com LocBaml, execute o seguinte para analisar LocBaml /parse RunDialog.resources.dll /out:, a fim de gerar um arquivo “RunDialog.resources.dll.CSV”.

Aviso

A ferramenta LocBaml só funciona com WPF para projetos do .NET Framework, não funciona com WPF para .NET.

Localize

Use seu editor de CSV favorito que dá suporte a Unicode para editar esse arquivo. Filtre todas as entradas com a categoria de localização “Nenhum”. Você deverá ver as seguintes entradas:

Chave de Recurso	Categoria de Localização	Valor
Button_1:System.Windows.Controls.Button.$Content	Botão	OK
Button_2:System.Windows.Controls.Button.$Content	Botão	Cancelar
Button_3:System.Windows.Controls.Button.$Content	Botão	Procurar...
ComboBox_1:System.Windows.Controls.ComboBox.$Content	ComboBox
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Texto	Digite o nome de um programa, uma pasta, um documento ou recurso da Internet e o Windows o abrirá para você.
TextBlock_2:System.Windows.Controls.TextBlock.$Content	Texto	Abrir:
Window_1:System.Windows.Window.Title	Título	Executar

A localização do aplicativo para o alemão exigirá as seguintes traduções:

Chave de Recurso	Categoria de Localização	Valor
Button_1:System.Windows.Controls.Button.$Content	Botão	OK
Button_2:System.Windows.Controls.Button.$Content	Botão	Abbrechen
Button_3:System.Windows.Controls.Button.$Content	Botão	Durchsuchen…
ComboBox_1:System.Windows.Controls.ComboBox.$Content	ComboBox
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Texto	Geben Sie den Namen eines Programms, Ordners, Dokuments oder einer Internetresource an.
TextBlock_2:System.Windows.Controls.TextBlock.$Content	Texto	Öffnen:
Window_1:System.Windows.Window.Title	Título	Executar

Generate

A última etapa da localização envolve a criação do assembly satélite recém-localizado. Faça isso com o seguinte comando do LocBaml:

LocBaml.exe /generate RunDialog.resources.dll /trans:RunDialog.resources.dll.CSV /out: . /cul:de-DE

No Windows alemão, se esse recurso.dll for colocado em uma pasta de-DE ao lado do assembly principal, esse recurso será carregado automaticamente em vez daquele na pasta en-US. Se você não tiver uma versão em alemão do Windows para testar isso, defina a cultura para qualquer cultura do Windows que você está usando (por exemplo, en-US) e substitua a DLL de recursos original.

Carregamento de recursos satélite

MyDialog.exe	en-US\MyDialog.resources.dll	de-DE\MyDialog.resources.dll
Código	BAML original em inglês	BAML localizado
Recursos com neutralidade de cultura	Outros recursos em inglês	Outros recursos localizados para o alemão

O Thread.CurrentUICulture.NET escolhe automaticamente qual assembly de recursos satélite carregar com base no . Isso usa como padrão a cultura do seu sistema operacional Windows. Se você estiver usando o Windows alemão, o arquivo de-DE\MyDialog.resources.dll será carregado. Se você estiver usando o Windows em inglês, o arquivo en-US\MyDialog.resources.dll será carregado. Você pode definir o recurso de fallback final para seu aplicativo especificando o NeutralResourcesLanguage atributo no arquivo AssemblyInfo do projeto. Por exemplo, se você especificar:

[assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)]

em seguida, o arquivo en-US\MyDialog.resources.dll é usado com o Windows alemão se nenhum dos seguintes arquivos estiver disponível: de-DE\MyDialog.resources.dll ou de\MyDialog.resources.dll.

Home page da Microsoft na Arábia Saudita

Os gráficos a seguir mostram uma home page em inglês e em árabe. Para obter a amostra completa que produz esses elementos gráficos, consulte Amostra de globalização de home page.

Inglês:

Screenshot showing an English home page.

Árabe:

Screenshot showing an Arabic home page.

Criando uma home page global da Microsoft

Este exemplo fictício do site da Microsoft na Arábia Saudita ilustra os recursos de globalização fornecidos para idiomas RightToLeft. Idiomas como hebraico e árabe têm uma ordem de leitura da direita para a esquerda, portanto, o layout da interface do usuário geralmente deve ser disposto de forma bem diferente do que seria em idiomas da esquerda para a direita, como o inglês. A localização de um idioma da esquerda para a direita para um idioma da direita para a esquerda ou vice-versa pode apresentar muitos desafios. WPF foi projetado para tornar essas localizações muito mais fácil.

FlowDirection

Homepage.xaml:

<Page x:Uid="Page_1" x:Class="MicrosoftSaudiArabiaHomepage.Homepage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"   
    FlowDirection="LeftToRight" 
    Localization.Comments="FlowDirection(This FlowDirection controls the actual content of the homepage)"
    xml:lang="en-US">

Observe a FlowDirection propriedade em Page. Alterar essa propriedade para alterará os FlowDirection Page elementos do e seus filhos para que o layout dessa interface do usuário seja invertido para RightToLeft se tornar da direita para a esquerda como um usuário árabe esperaria. Pode-se substituir o comportamento de herança especificando um explícito FlowDirection em qualquer elemento. A FlowDirection propriedade está disponível em qualquer FrameworkElement elemento relacionado ao documento e tem um valor implícito de LeftToRight.

Observe que até mesmo os pincéis de gradiente de plano de fundo são invertidos corretamente quando a raiz FlowDirection é alterada:

FlowDirection="LeftToRight"

Screenshot showing the gradient flow from left to right.

FlowDirection="RightToLeft"

Screenshot showing the gradient flow from right to left.

Evitar usar dimensões fixas para painéis e controles

Dê uma olhada em Homepage.xaml, observe que, além da largura e altura fixas especificadas para toda a interface do usuário na parte superior DockPanel, não há outras dimensões fixas. Evite usar dimensões fixas para evitar o recorte do texto localizado, que pode ser maior que o texto de origem. Os painéis e controles do WPF serão redimensionados automaticamente com base no conteúdo que eles contêm. A maioria dos controles também tem dimensões mínimas e máximas que você pode definir para mais controle (por exemplo, MinWidth="20"). Com Grido , você também pode definir larguras e alturas relativas usando '*' (por exemplo, Width="0.25*") ou usar seu recurso de compartilhamento de tamanho de célula.

Comentários de localização

Há muitos casos em que o conteúdo pode ser ambíguo e difícil de ser traduzido. O desenvolvedor ou o designer tem a capacidade de fornecer um contexto extra e comentários para os localizadores por meio de comentários de localização. Por exemplo, o Localization.Comments abaixo esclarece o uso do caractere '|'.

<TextBlock 
  x:Uid="TextBlock_2" 
  DockPanel.Dock="Right" 
  Foreground="White" 
  Margin="5,0,5,0"
  Localization.Comments="$Content(This character is used as a decorative rule.)">
  |
</TextBlock>

Este comentário torna-se associado ao conteúdo de TextBlock_1 e, no caso da ferramenta LocBaml, ( consulte Localizar um aplicativo), ele pode ser visto na 6ª coluna da linha TextBlock_1 no arquivo de .csv de saída:

Chave de Recurso	Categoria	Legível	Modificável	Comentar	Valor
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Texto	TRUE	TRUE	Esse caractere é usado como uma regra decorativa.	\|

Os comentários podem ser colocados no conteúdo ou na propriedade de qualquer elemento com a seguinte sintaxe:

<TextBlock 
  x:Uid="TextBlock_1" 
  DockPanel.Dock="Right" 
  Foreground="White" 
  Margin="5,0,5,0"
  Localization.Comments="$Content(This is a comment on the TextBlock's content.)
     Margin(This is a comment on the TextBlock's Margin property.)">
  |
 </TextBlock>

Atributos de Localização

De modo geral, o desenvolvedor ou o gerente de localização precisa controlar o que os localizadores podem ler e modificar. Por exemplo, talvez você não deseje que o localizador traduza o nome de sua empresa ou palavras que se referem ao conteúdo legal. O WPF fornece atributos que permitem definir a legibilidade, a modificabilidade e a categoria do conteúdo ou da propriedade de um elemento que sua ferramenta de localização pode usar para bloquear, ocultar ou classificar elementos. Para obter mais informações, consulte Attributes. Para as finalidades desta amostra, a ferramenta LocBaml somente gera os valores desses atributos. Todos os controles WPF têm valores padrão para esses atributos, mas você pode substituí-los. Por exemplo, o exemplo a seguir substitui os atributos de localização padrão e TextBlock_1 define o conteúdo como legível, mas não modificável para localizadores.

<TextBlock
x:Uid="TextBlock_1"
Localization.Attributes=
"$Content(Readable Unmodifiable)">
  Microsoft Corporation
</TextBlock>

Além dos atributos de legibilidade e modificabilidade, o WPF fornece uma enumeração de categorias comuns da interface do usuário (LocalizationCategory) que podem ser usadas para dar mais contexto aos localizadores. As categorias padrão do WPF para controles de plataforma também podem ser substituídas em XAML:

<TextBlock x:Uid="TextBlock_2">
<TextBlock.ToolTip>
<TextBlock
x:Uid="TextBlock_3"
Localization.Attributes=
"$Content(ToolTip Readable Unmodifiable)">
Microsoft Corporation
</TextBlock>
</TextBlock.ToolTip>
Windows Vista
</TextBlock>

Os atributos de localização padrão que o WPF fornece também podem ser substituídos por meio de código, para que você possa definir corretamente os valores padrão corretos para controles personalizados. Por exemplo:

[Localizability(Readability = Readability.Readable, Modifiability=Modifiability.Unmodifiable, LocalizationCategory.None)]
public class CorporateLogo : TextBlock
{
    // ...
}

Os atributos por instância definidos em XAML terão precedência sobre os valores definidos no código em controles personalizados. Para obter mais informações sobre atributos e comentários, consulte Atributos e comentários de localização.

Fallback de fontes e fontes de composição

Se você especificar uma fonte que não ofereça suporte a um determinado intervalo de pontos de código, o WPF fará fallback automaticamente para um que o faça usando a Global User Interface.compositefont localizada no diretório Windows\Fonts. As fontes compostas funcionam como qualquer outra fonte e podem ser usadas explicitamente definindo a de FontFamily um elemento (por exemplo, FontFamily="Global User Interface"). Você pode especificar sua própria preferência de fallback de fontes criando sua própria fonte de composição e especificando qual fonte será usada para intervalos de ponto de código e idiomas específicos.

Para obter mais informações sobre fontes compostas, consulte FontFamily.

Localizando a home page da Microsoft

É possível seguir as mesmas etapas do exemplo da Caixa de Diálogo Executar para localizar esse aplicativo. O arquivo .csv localizado para o árabe está disponível para você na Amostra de globalização de home page.

Compartilhar via