Como localizar um aplicativo

Artigo
06/02/2023

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

Observação

A ferramenta LocBaml não é um aplicativo pronto para produção. Ela é apresentada 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 Windows Presentation Foundation (WPF), é 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 Exemplo de ferramenta LocBaml.

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 é o HelloApp.csproj. Nesse arquivo, você encontrará a linguagem de desenvolvimento identificada da seguinte maneira:

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

msbuild -t:updateuid helloapp.csproj

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

msbuild -t:checkuid helloapp.csproj

Depois de executar updateuido , seus arquivos devem conter Uids. Por exemplo, no arquivo Pane1.xaml de 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 linguagem neutra

Depois que o aplicativo é configurado para gerar um assembly satélite de recursos de linguagem neutra, você cria o aplicativo. Isso gera o assembly do aplicativo principal, bem como o assembly satélite de recursos de linguagem neutra que é exigido pelo LocBaml para localização.

Para criar o aplicativo:

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

msbuild helloapp.csproj
O assembly de aplicativo principal recém-criado, HelloApp.exe, é criado na seguinte pasta: C: \HelloApp\Bin\Debug
O assembly satélite de recursos de linguagem neutra 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 construir o LocBaml estão localizados nos exemplos do WPF. Baixe os arquivos C# do exemplo de ferramenta LocBaml.
Na linha de comando, execute o arquivo de projeto (locbaml.csproj) para compilar 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` {filedirectory]	Nome do arquivo de saída.
`culture` ou `-cul` {cultura]	Localidade dos assemblies de saída.
`translation` ou `-trans` {tradução.csv]	Arquivo traduzido ou localizado.
`asmpath` ou `-asmpath` {filedirectory]	Se o código XAML contiver controles personalizados, você deverá fornecer o para o `asmpath` assembly de controle personalizado.
`nologo`	Não exibe nenhum logotipo ou informações de direitos autorais.
`verbose`	Exibe informações detalhadas do modo.

Observação

Se você precisar de uma lista das opções quando estiver executando a ferramenta, digite 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 o LocBaml.exe para a pasta bin\debug do aplicativo, em que 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

Observação

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

Ao executar a LocBaml para analisar arquivos, a saída consistirá em sete campos delimitados por vírgulas (arquivos .csv) ou tabulações (arquivos .txt). A seguir está o arquivo .csv analisado do 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 do 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	TRUE	TRUE	Olá, Mundo
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Nenhum	TRUE	TRUE	Goodbye World

Observe que todos os valores para o campo Comentários não contêm nenhum valor. Se um campo não tem um valor, ele está vazio. Observe também que o item na primeira linha não é legível nem modificável e tem "Ignore" como seu valor Categoria, indicando que o valor não é localizável.

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

Traduzir o conteúdo localizável

Use qualquer ferramenta que você tiver 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 conversão na última coluna (valor).

Use LocBaml para gerar um novo arquivo .resources.dll

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

Use a seguinte sintaxe 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

Observação

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 estejam no mesmo diretório.
Substitua o arquivo HelloApp.resources.dll antigo no diretório C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll pelo arquivo HelloApp.resources.dll recém-criado.
"Hello World" e "Goodbye World" agora devem estar traduzidos em seu aplicativo.
Para traduzir para uma cultura diferente, use a cultura do idioma para o 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 assembly satélite, você precisa alterar a cultura na qual o aplicativo será executado. É possível fazer isso de duas formas:

Altere as configurações regionais do sistema operacional.

Em seu aplicativo, adicione o seguinte código em 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 LocBaml

Todos os assemblies dependentes que definem controles personalizados devem ser copiados para o diretório local da LocBaml ou instalados no GAC. Isso é necessário porque a API de localização deve ter acesso aos assemblies dependentes quando lê o XAML binário (BAML).
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