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

Artigo
01/30/2025

Quando você limita a disponibilidade do produto a apenas um idioma, limita sua base de clientes potencial a uma fração dos 7,5 bilhões de habitantes do nosso mundo. Se você quiser que seus aplicativos atinjam um público-alvo global, a localização econômica do seu produto é uma das melhores e mais econômicas maneiras de alcançar mais clientes.

Essa visão geral apresenta a globalização e a localização no WPF (Windows Presentation Foundation). A globalização é o design e o desenvolvimento de aplicativos que são executados em vários locais. Por exemplo, a globalização dá suporte a interfaces de usuário localizadas e dados regionais para usuários em diferentes culturas. O WPF oferece funcionalidades de design globalizadas, incluindo disposição automática, assemblies satélites, atributos localizados e comentários.

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

Aviso

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

Práticas recomendadas para 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 que esta seção fornece.

Práticas recomendadas para design de interface do usuário do WPF

Ao criar uma interface do usuário baseada em WPF, considere implementar estas 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 definir o conteúdo; em vez disso, use o dimensionamento relativo ou automático.
- Use SizeToContent e mantenha as larguras e as alturas definidas como Auto.
- Evite usar Canvas para projetar interfaces de usuário.
- Use Grid e o respectivo recurso de compartilhamento de tamanho.
Forneça espaço extra nas margens porque o texto localizado geralmente requer mais espaço. O espaço extra permite possíveis caracteres estendidos.
Habilite TextWrapping em TextBlock para evitar recortes.
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 de fontes que são usadas para idiomas diferentes. 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 herda FlowDirection do NavigationWindow.
Ao criar aplicativos de navegação autônomos hospedados fora de um navegador, defina o StartupUri para seu aplicativo inicial como um NavigationWindow em vez de uma página (por exemplo, <Application StartupUri="NavigationWindow.xaml">). Esse design permite que você altere o FlowDirection da janela e da barra de navegação. Para obter mais informações e um exemplo, consulte Amostra de globalização de home page.

Práticas recomendadas para localização em WPF

Ao localizar aplicativos baseados em WPF, considere implementar estas 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 seletivamente propriedades Uid em elementos. Consulte Atributos e comentários de localização para obter mais informações.
Use msbuild -t:updateuid e -t:checkuid para adicionar e verificar a propriedade Uid em seu XAML. Use as propriedades Uid para acompanhar as alterações entre desenvolvimento e localização. As propriedades de Uid ajudam você a localizar alterações recentes no desenvolvimento. Se você adicionar manualmente propriedades Uid a uma interface do usuário, a tarefa normalmente será entediante e menos precisa.
- Não edite nem altere as propriedades Uid após iniciar a localização.
- Não use propriedades de Uid duplicadas (lembre-se dessa dica ao usar o comando copiar e colar).
- Defina a localização UltimateResourceFallback em AssemblyInfo.* para especificar o 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 marca <UICulture> no arquivo de projeto, defina o local UltimateResourceFallback como o assembly principal em vez do satélite (por exemplo, [assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.MainAssembly)]).

Localizar um aplicativo WPF

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

Você pode localizar depois de compilar.
Você pode atualizar para uma versão mais recente do formato BAML de XAML, utilizando localizações de uma versão mais antiga, para que possa traduzir e adaptar enquanto desenvolve.
Você pode validar elementos de origem originais e 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 build para localização é o seguinte:

O desenvolvedor cria e globaliza o aplicativo WPF. No arquivo de projeto, o desenvolvedor define <UICulture>en-US</UICulture> para que, quando o aplicativo é compilado, seja gerado um assembly principal neutro em linguagem. 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 dão suporte à extração do assembly principal.
Quando o arquivo é compilado no build, o XAML é convertido na forma BAML do XAML. O arquivo MyDialog.exe culturalmente neutro e os arquivos MyDialog.resources.dll culturalmente dependentes (inglês) são entregues ao cliente falante de 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 as propriedades da interface do usuário no seu XAML original são extraídos da forma BAML do XAML em pares de chave-valor usando as APIs em System.Windows.Markup.Localizer. Os localizadores usam os pares chave-valor para localizar o aplicativo. Você pode gerar um novo .resource.dll a partir dos novos valores após a conclusão da localização.

As chaves dos pares chave-valor são valores x:Uid que o desenvolvedor insere no XAML original. Esses valores x:Uid permitem que a API acompanhe 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 de localização típico baseado na forma BAML de XAML. Esse diagrama pressupõe que o desenvolvedor grave o aplicativo em inglês. O desenvolvedor cria e globaliza o aplicativo WPF. No arquivo de projeto, o desenvolvedor define <UICulture>en-US</UICulture> para que, durante o build, um assembly principal com neutralidade de idioma seja gerado com um .resources.dll satélite que contém todos os recursos localizáveis. Como alternativa, é possível manter o idioma de origem no assembly principal porque as APIs de localização do WPF dão suporte à extração do assembly principal. Após o processo de build, o XAML é compilado no BAML. Os MyDialog.exe.resources.dll, que são culturalmente neutros, são enviados para os clientes de língua inglesa.

Diagrama mostrando o fluxo de trabalho de Localização.

Diagrama mostrando o fluxo de trabalho não localizado.

Exemplos de localização do 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:

Captura de tela mostrando uma caixa de diálogo Executar em inglês.

alemão:

Captura de tela mostrando uma caixa de diálogo Executar em alemão.

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 disponível no menu Iniciar do Microsoft Windows.

Alguns destaques para criar 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; 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">

Propriedades Uid 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 acompanhar as alterações entre o desenvolvimento e a localização da interface do usuário. As propriedades Uid permitem mesclar uma versão mais recente da UI com uma localização mais antiga da UI. Adicione uma propriedade Uid executando msbuild -t:updateuid RunDialog.csproj em um shell de comando. Esse é o método recomendado para adicionar propriedades Uid porque adicioná-las manualmente normalmente é demorada e menos precisa. Você pode verificar se as propriedades de Uid estão definidas corretamente executando msbuild -t:checkuid RunDialog.csproj.

A interface do usuário é estruturada usando o controle Grid, que é um controle útil para aproveitar o 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 de 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 Abrir: rótulo 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 de Grid. As últimas três colunas se beneficiam disso posicionando-se no mesmo SharedSizeGroup. Como seria de esperar do nome da propriedade, isso permite que as colunas compartilhem o mesmo tamanho. Então, quando o "Procurar..." é localizado para a cadeia de caracteres mais longa “Durchsuchen...”, todos os botões crescem em largura, em vez de haver um botão “OK” pequeno e um botão “Durchsuchen…” desproporcionalmente grande.

xml:lang

xml:lang="en-US"

Observe que a manipulação de xml:lang no XAML é colocada 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 é usado para hifenizar e verificar a ortografia das palavras. Ele também afeta a exibição de dígitos e como o sistema de substituição de fontes seleciona qual fonte usar. Por fim, a propriedade afeta a forma como os números são exibidos e a forma como os textos escritos em scripts complexos são moldados. O valor padrão é "en-US".

Compilando um assembly de recursos satélite

Em .csproj:

Edite o arquivo .csproj e adicione a seguinte tag a um <PropertyGroup>que seja incondicional:

<UICulture>en-US</UICulture>

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

<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 está definido como false para que ele permaneça na assemblagem principal neutra em relação à linguagem em vez de na assemblagem 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 os fins deste tópico, use a ferramenta de exemplo LocBaml, que pode ser encontrada em Exemplo de Ferramenta LocBaml. Observe que o LocBaml é apenas uma ferramenta de exemplo destinada a ajudá-lo a começar a criar uma ferramenta de localização que se ajuste ao processo de localização. Usando LocBaml, execute o seguinte para parsear: LocBaml /parse RunDialog.resources.dll /out: para gerar um "RunDialog.resources.dll.CSV" arquivo.

Aviso

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

Localizar

Use o editor CSV favorito que dá suporte ao 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	OKEY
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, pasta, 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	Correr

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

Chave de Recurso	Categoria de localização	Valor
Button_1:System.Windows.Controls.Button.$Content	Botão	OKEY
Button_2:System.Windows.Controls.Button.$Content	Botão	Cancelar
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	Correr

Gerar

A última etapa da localização envolve a criação da nova assembléia de satélite localizada. Isso pode ser feito com o seguinte comando LocBaml:

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

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

Carregamento de Recursos de Satélite

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

O .NET escolhe automaticamente quais assemblies de recursos satélites carregar com base no Thread.CurrentUICulturedo aplicativo. Isso usa como padrão a cultura do 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 atributo NeutralResourcesLanguage no arquivo AssemblyInfo do seu projeto. Por exemplo, se você especificar:

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

em seguida, o arquivo en-US\MyDialog.resources.dll será 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 Arábia Saudita

Os gráficos a seguir mostram uma home page em inglês e árabe. Para o exemplo completo que produz esses gráficos, confira Exemplo de Página Inicial de Globalização.

Inglês:

Captura de tela mostrando uma home page em inglês.

Árabe:

Captura de tela mostrando uma home page árabe.

Criando uma home page global da Microsoft

Essa simulação do site da Microsoft 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 deve muitas vezes ser disposto de forma bastante 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. O WPF foi projetado para facilitar muito essas localizações.

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 propriedade FlowDirection em Page. Alterar essa propriedade para RightToLeft alterará o FlowDirection do Page e de seus elementos filhos para que o layout dessa interface do usuário seja invertido para que se torne da direita para a esquerda, como um usuário árabe esperaria. É possível substituir o comportamento da herança especificando um FlowDirection de maneira explícita em qualquer elemento. A propriedade FlowDirection está disponível em qualquer elemento relacionado a FrameworkElement ou documento e tem um valor implícito de LeftToRight.

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

FlowDirection="LeftToRight"

Captura de tela mostrando o fluxo de gradiente da esquerda para a direita.

DireçãoDoFluxo="DaDireitaParaAEsquerda"

Captura de tela mostrando o fluxo de gradiente da direita para a esquerda.

evitar o uso de dimensões fixas para painéis e controles

Examine Homepage.xaml, observe que, além da largura fixa e da altura 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 impedir o recorte de texto localizado que pode ser maior que o texto de origem. Os painéis e controles do WPF serão redimensioná 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 Grid, 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 traduzir. O desenvolvedor ou designer tem a capacidade de fornecer contexto extra e comentários aos 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>

Esse 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	Comentário	Valor
TextBlock_1:System.Windows.Controls.TextBlock.$Content	Texto	VERDADEIRO	VERDADEIRO	Esse caractere é usado como uma regra decorativa.	\|

Os comentários podem ser colocados no conteúdo ou na propriedade de qualquer elemento usando 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

Muitas vezes, o desenvolvedor ou o gerenciador de localização precisa de controle do que os localizadores podem ler e modificar. Por exemplo, talvez você não queira que o localizador traduza o nome da sua empresa ou a redação 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 fins deste exemplo, a Ferramenta LocBaml apenas gera os valores desses atributos. Todos os controles do 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 para TextBlock_1 e 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 de 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 no 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 fornecidos pelo WPF também podem ser substituídos por meio do 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 de Localização e Comentários.

Fallback de fontes e fontes de composição

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

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

Localizando a página inicial 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