Como localizar um aplicativo

Artigo
01/30/2025

Este tutorial explica como criar um aplicativo localizado usando a ferramenta LocBaml.

Nota

A ferramenta LocBaml não é um aplicativo pronto para produção. Ele é apresentado como um exemplo que usa algumas das APIs de localização e ilustra como você pode escrever uma ferramenta de localização.

Visão geral

Este artigo fornece uma abordagem passo a passo para localizar um aplicativo. Primeiro, você prepara seu aplicativo para que o texto que será traduzido possa ser extraído. Depois que o texto é traduzido, você mescla o texto traduzido em uma nova cópia do aplicativo original.

Criar um aplicativo de exemplo

Nesta etapa, você prepara seu aplicativo para localização. Nos exemplos do WPF (Windows Presentation Foundation), é fornecido um exemplo de HelloApp que será usado para os exemplos de código nesta discussão. Se você quiser usar este exemplo, baixe os arquivos XAML (Extensible Application Markup Language) do LocBaml Tool Sample.

Desenvolva seu aplicativo até o ponto em que você deseja iniciar a localização.
Especifique a linguagem de desenvolvimento no arquivo de projeto para que o MSBuild gere um assembly principal e um assembly satélite (um arquivo com a extensão .resources.dll) para conter os recursos de linguagem neutra. O arquivo de projeto no exemplo helloapp é HelloApp.csproj. Nesse arquivo, você encontrará a linguagem de desenvolvimento identificada da seguinte maneira:

<UICulture>en-US</UICulture>
Adicione Uids aos arquivos XAML. Os Uids são usados para controlar as alterações nos arquivos e identificar itens que devem ser traduzidos. Para adicionar Uids aos seus arquivos, execute updateuid no arquivo de projeto:

msbuild -t:updateuid helloapp.csproj

Para verificar se você não tem Uids ausentes ou duplicadas, execute checkuid:

msbuild -t:checkuid helloapp.csproj

Depois de executar updateuid, seus arquivos devem conter Uids. Por exemplo, no arquivo Pane1.xaml do HelloApp, você deve encontrar o seguinte:
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

Criar o assembly satélite de recursos de idioma neutro

Depois que o aplicativo é configurado para gerar um assembly satélite de recursos de idioma neutro, você compila o aplicativo. Isso gera o assembly principal do aplicativo, assim como o assembly satélite de recursos com idioma neutro exigido pelo LocBaml para localização.

Para criar o aplicativo:

Compile o HelloApp para criar uma DLL (biblioteca de vínculo dinâmico):

msbuild helloapp.csproj
O assembly principal do aplicativo recém-criado, HelloApp.exe, está na seguinte pasta: C:\HelloApp\Bin\Debug
O assembly satélite de recursos de idioma neutro recém-criado, HelloApp.resources.dll, é criado na seguinte pasta: C:\HelloApp\Bin\Debug\en-US

Criar a ferramenta LocBaml

Todos os arquivos necessários para criar LocBaml estão localizados nos exemplos do WPF. Baixe os arquivos C# do Sample da ferramenta LocBaml.
Na linha de comando, execute o arquivo de projeto (locbaml.csproj) para criar a ferramenta:

msbuild locbaml.csproj
Vá para o diretório Bin\Release para localizar o arquivo executável recém-criado (locbaml.exe). Exemplo: C:\LocBaml\Bin\Release\locbaml.exe

As opções que você pode especificar ao executar o LocBaml são as seguintes.

Opção	Descrição
`parse` ou `-p`	Analisa arquivos Baml, recursos ou DLL para gerar um arquivo .csv ou .txt.
`generate` ou `-g`	Gera um arquivo binário localizado usando um arquivo traduzido.
`out` ou `-o` {diretório de arquivos]	Nome do arquivo de saída.
`culture` ou `-cul` {cultura]	Localidade de assemblies de saída.
`translation` ou `-trans` {translation.csv]	Arquivo traduzido ou localizado.
`asmpath` ou `-asmpath` {diretório de arquivos]	Se o código XAML contiver controles personalizados, você deverá fornecer o `asmpath` ao conjunto de controle personalizado.
`nologo`	Não exibe nenhum logotipo ou informações de direitos autorais.
`verbose`	Exibe informações no modo detalhado.

Nota

Se você precisar de uma lista das opções ao executar a ferramenta, insira LocBaml.exe e pressione Enter.

Usar LocBaml para analisar um arquivo

Agora que criou a ferramenta LocBaml, você está pronto para usá-la para analisar o HelloApp.resources.dll e extrair o conteúdo de texto que será localizado.

Copie LocBaml.exe para a pasta bin\debug do aplicativo, na qual o assembly principal do aplicativo foi criado.
Para analisar o arquivo do assembly satélite e armazenar o resultado como um arquivo .csv, use o seguinte comando:

LocBaml.exe /parse HelloApp.resources.dll /out:Hello.csv

Nota

Se o arquivo de entrada, HelloApp.resources.dll, não estiver no mesmo diretório que LocBaml.exe mover um dos arquivos para que ambos os arquivos estejam no mesmo diretório.

Quando você executa o LocBaml para analisar arquivos, a saída consiste em sete campos delimitados por vírgulas (arquivos.csv) ou guias (arquivos.txt). O seguinte mostra o arquivo de .csv analisado para o HelloApp.resources.dll:

Arquivo .csv analisado
HelloApp.g.en-US.resources:window1.baml,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;
HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Hello World
HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World

Os sete campos são:

Nome BAML. O nome do recurso BAML em relação ao assembly satélite do idioma de origem.
Chave de recurso. O identificador de recurso localizado.
Categoria. O tipo de valor. Consulte Atributos de localização e comentários.
Legibilidade. Se o valor pode ser lido por um localizador. Consulte Atributos de localização e comentários.
Modificabilidade. Se o valor pode ser modificado por um localizador. Consulte Atributos de localização e comentários.
Comentários. Descrição adicional do valor para ajudar a determinar como um valor é localizado. Consulte Atributos de localização e comentários.
Valor. O valor de texto a traduzir para a cultura desejada.

A tabela a seguir mostra como esses campos são mapeados para os valores delimitados do arquivo .csv:

Nome BAML	Chave de recurso	Categoria	Legibilidade	Modificabilidade	Valor
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Ignorar	FALSE	FALSE	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	Nenhum	VERDADEIRO	VERDADEIRO	Olá, mundo
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Nenhum	VERDADEIRO	VERDADEIRO	Adeus Mundo

Observe que todos os valores do campo Comentários não contêm valores; se um campo não tiver um valor, ele estará vazio. Observe também que o item na primeira linha não é legível nem modificável e tem "Ignore" como seu valor categoria , o que indica que o valor não é localizável.

Para facilitar a descoberta de itens localizáveis em arquivos analisados, especialmente em arquivos grandes, você pode classificar ou filtrar os itens por Categoria , Legibilidade e Modificabilidade . Por exemplo, você pode filtrar valores ilegíveis e não modificáveis.

Traduzir o conteúdo localizável

Use qualquer ferramenta disponível para traduzir o conteúdo extraído. Uma boa maneira de fazer isso é gravar os recursos em um arquivo .csv e exibi-los no Microsoft Excel, fazendo alterações de tradução para a última coluna (valor).

Usar LocBaml para gerar um novo arquivo de .resources.dll

O conteúdo que foi identificado analisando HelloApp.resources.dll com LocBaml foi convertido e deve ser mesclado novamente no aplicativo original. Use a opção generate ou -g para gerar um novo arquivo de .resources.dll.

Use a sintaxe a seguir para gerar um novo arquivo HelloApp.resources.dll. Marque a cultura como en-US (/cul:en-US).

LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US

Nota

Se o arquivo de entrada, Hello.csv, não estiver no mesmo diretório que o executável, LocBaml.exe, mova um dos arquivos para que ambos os arquivos estejam no mesmo diretório.
Substitua o arquivo de HelloApp.resources.dll antigo no diretório C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll pelo arquivo de HelloApp.resources.dll recém-criado.
"Hello World" e "Goodbye World" agora devem ser traduzidos em seu aplicativo.
Para traduzir para uma cultura diferente, use a cultura da linguagem para a qual você está traduzindo. O exemplo a seguir mostra como traduzir para francês-canadense:

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
No mesmo assembly que o assembly principal do aplicativo, crie uma nova pasta específica de cultura para abrigar o novo assembly satélite. Para francês canadense, a pasta seria fr-CA.
Copie o assembly satélite gerado para a nova pasta.

Para testar o novo conjunto de satélite, você precisa alterar a cultura de execução na qual seu aplicativo será executado. Você pode fazer isso de duas maneiras:

Altere as configurações regionais do sistema operacional.

Em seu aplicativo, adicione o seguinte código a App.xaml.cs:

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="SDKSample.App"
    x:Uid="Application_1"
    StartupUri="Window1.xaml">
</Application>

using System.Windows;
using System.Globalization;
using System.Threading;

namespace SDKSample
{
    public partial class App : Application
    {
        public App()
        {
            // Change culture under which this application runs
            CultureInfo ci = new CultureInfo("fr-CA");
            Thread.CurrentThread.CurrentCulture = ci;
            Thread.CurrentThread.CurrentUICulture = ci;
        }
    }
}


Imports System.Windows
Imports System.Globalization
Imports System.Threading

Namespace SDKSample
    Partial Public Class App
        Inherits Application
        Public Sub New()
            ' Change culture under which this application runs
            Dim ci As New CultureInfo("fr-CA")
            Thread.CurrentThread.CurrentCulture = ci
            Thread.CurrentThread.CurrentUICulture = ci
        End Sub
    End Class
End Namespace

Dicas para usar o LocBaml

Todos os assemblies dependentes que definem controles personalizados devem ser copiados no diretório local do LocBaml ou instalados no GAC. Isso é necessário porque a API de localização deve ter acesso aos assemblies dependentes quando lê o BAML (XAML binário).
Se o assembly principal é assinado, a DLL de recurso gerado também deve ser assinada para que seja carregada.
A versão da DLL de recurso localizado precisa ser sincronizada com o assembly principal.

Compartilhar via