Procedimiento: Localizar una aplicación

Artículo
05/04/2023

En este tutorial se explica cómo crear una aplicación localizada mediante la herramienta LocBaml.

Nota:

La herramienta LocBaml no es una aplicación lista para producción. Se presenta como un ejemplo que usa algunas de las API de localización y muestra cómo se podría escribir una herramienta de localización.

Información general

En este artículo se ofrece un enfoque detallado para la localización de una aplicación. En primer lugar, prepare su aplicación para que se puede extraer el texto que se va a traducir. Una vez traducido el texto, tiene que combinar el texto traducido en una nueva copia de la aplicación original.

Crear una aplicación de ejemplo

En este paso, prepare la aplicación para la localización. En los ejemplos de Windows Presentation Foundation (WPF) se proporciona una HelloApp que se usará para los ejemplos de código de este artículo. Si quiere usar este ejemplo, descargue los archivos de Lenguaje de marcado de aplicaciones extensible (XAML) desde LocBaml Tool Sample (Ejemplo de la herramienta LocBaml).

Desarrolle su aplicación hasta el punto donde desea iniciar la localización.
Especifique el lenguaje de desarrollo en el archivo de proyecto para que MSBuild genere un ensamblado principal y un ensamblado satélite (archivo con la extensión .resources.dll) para incluir los recursos de idioma neutro. El archivo de proyecto en el ejemplo HelloApp es HelloApp.csproj. En ese archivo, encontrará el lenguaje de desarrollo que se identifica como sigue:

<UICulture>en-US</UICulture>
Agregue UID a sus archivos XAML. Los UID se usan para realizar un seguimiento de los cambios en los archivos y para identificar los elementos que se deben traducir. Para agregar los UID a los archivos, ejecute updateuid en el archivo de proyecto:

msbuild -t:updateuid helloapp.csproj

Para comprobar que no faltan UID ni están duplicados, ejecute checkuid:

msbuild -t:checkuid helloapp.csproj

Después de ejecutar updateuid, los archivos deberían contener los UID. Por ejemplo, en el archivo Pane1.xaml de HelloApp, busque lo siguiente:
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

Crear el ensamblado satélite de recursos de idioma neutro

Después de configurar la aplicación para que genere un ensamblado satélite de recursos de idioma neutro, compile la aplicación. Esto genera el ensamblado de aplicación principal, así como el ensamblado satélite de recursos de idioma neutro que LocBaml necesita para la localización.

Para compilar la aplicación:

Compile HelloApp para crear una biblioteca de vínculos dinámicos (DLL):

msbuild helloapp.csproj
El ensamblado de aplicación principal que se acaba de crear, HelloApp.exe, se encuentra en la carpeta siguiente: C:\HelloApp\Bin\Debug
El ensamblado satélite de recursos de idioma neutro que se acaba de crear, HelloApp.resources.dll, se crea en la carpeta siguiente: C:\HelloApp\Bin\Debug\en-US

Compilar la herramienta LocBaml

Todos los archivos necesarios para compilar LocBaml se encuentran en los ejemplos de WPF. Descargue los archivos C# desde LocBaml Tool Sample (Ejemplo de la herramienta LocBaml).
Desde la línea de comandos, ejecute el archivo de proyecto (locbaml.csproj) para compilar la herramienta:

msbuild locbaml.csproj
Vaya al directorio Bin\Release para buscar el archivo ejecutable recién creado (locbaml.exe). Ejemplo: C:\LocBaml\Bin\Release\locbaml.exe

Las opciones que puede especificar al ejecutar LocBaml son las siguientes.

Opción	Descripción
`parse` o `-p`	Analiza archivos Baml, recursos o DLL para generar un archivo .csv o .txt.
`generate` o `-g`	Genera un archivo binario localizado utilizando un archivo traducido.
`out` o `-o` {filedirectory]	Nombre del archivo de salida.
`culture` o `-cul` {culture]	Ubicación de los ensamblados de salida.
`translation` o `-trans` {translation.csv]	Archivo traducido o localizado.
`asmpath` o `-asmpath` {filedirectory]	Si su código XAML contiene controles personalizados, debe suministrar el `asmpath` al ensamblado de controles personalizados.
`nologo`	no muestra un logotipo ni información de copyright.
`verbose`	muestra información en modo detallado.

Nota:

Si necesita una lista de las opciones cuando esté ejecutando la herramienta, introduzca LocBaml.exe y luego pulse Entrar.

Usar LocBaml para analizar un archivo

Ahora que ya ha creado la herramienta LocBaml, está listo para usarla para analizar HelloApp.resources.dll y extraer el contenido de texto que se traducirá.

Copie LocBaml.exe en la carpeta bin\debug de la aplicación, que es donde se creó el ensamblado de aplicación principal.
Para analizar el archivo de ensamblado satélite y almacenar la salida como un archivo .csv, use el siguiente comando:

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

Nota:

Si el archivo de entrada, HelloApp.resources.dll, no está en el mismo directorio que LocBaml.exe, mueva uno de los archivos para que ambos archivos se encuentren en el mismo directorio.

Cuando se ejecuta LocBaml para analizar los archivos, la salida se compone de siete campos delimitados por comas (archivos .csv) o tabuladores (archivos .txt). A continuación se muestra el archivo .csv analizado para HelloApp.resources.dll:

Archivo .csv analizado
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

Los siete campos son:

Nombre de BAML. Es el nombre del recurso BAML con respecto al ensamblado satélite de lenguaje de origen.
Clave de recurso. Es el identificador de recursos localizado.
Categoría. Tipo de valor. Consulte Atributos y comentarios sobre localización.
Legibilidad. Indica si un localizador puede leer el valor. Consulte Atributos y comentarios sobre localización.
Modificabilidad. Indica si un localizador puede modificar el valor. Consulte Atributos y comentarios sobre localización.
Comentarios. Descripción adicional del valor para ayudar a determinar cómo se localiza. Consulte Atributos y comentarios sobre localización.
Valor. Es el valor de texto que se va a traducir a la referencia cultural deseada.

En la tabla siguiente se muestra la correspondencia entre estos campos y los valores delimitados del archivo CSV:

Nombre de BAML	Clave del recurso	Category	Legibilidad	Modificabilidad	Value
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	Hola mundo
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	None	TRUE	TRUE	Goodbye World

Observe que todos los valores del campo Comentarios están vacíos; si un campo no contiene ningún valor, está vacío. Observe también que el elemento de la primera fila no es legible ni modificable y tiene "Ignore" como su valor de Categoría, lo que indica que el valor no es localizable.

Para facilitar la detección de los elementos localizables en los archivos analizados, especialmente en los archivos de gran tamaño, puede ordenar o filtrar los elementos por Categoría, Legibilidad y Modificabilidad. Por ejemplo, puede filtrar los valores ilegibles y no modificables.

Traducir el contenido Localizable

Use cualquier herramienta disponible traducir el contenido extraído. Una buena forma de hacerlo es escribir los recursos en un archivo .csv, verlos en Microsoft Excel y realizar los cambios de traducción cambios en la última columna (valor).

Usar LocBaml para generar un nuevo archivo .resources.dll

El contenido que se identificó al analizar HelloApp.resources.dll con LocBaml se ha traducido y debe combinarse en la aplicación original. Use la opción generate o -g para generar un nuevo archivo .resources.dll.

Use la sintaxis siguiente para generar un nuevo archivo HelloApp.resources.dll. Marque la referencia cultural como en-US (/cul:en-US).

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

Nota:

Si el archivo de entrada, Hello.csv, no está en el mismo directorio que el ejecutable, LocBaml.exe, mueva uno de los archivos para que ambos se encuentren en el mismo directorio.
Reemplace el archivo HelloApp.resources.dll anterior en el directorio C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll por el archivo HelloApp.resources.dll recién creado.
“Hello World” y “Goodbye World” deberían aparecer ya traducidos en la aplicación.
Para traducir a una referencia cultural diferente, use la referencia cultural del idioma al que va a traducir. En el ejemplo siguiente se muestra cómo traducir al francés canadiense:

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
En el mismo ensamblado que el ensamblado de aplicación principal, cree una nueva carpeta específica de la referencia cultural para alojar el nuevo ensamblado satélite. Para el francés canadiense, la carpeta sería fr-CA.
Copie el ensamblado satélite generado en la nueva carpeta.

Para probar el nuevo ensamblado satélite, deberá cambiar la referencia cultural en la que se ejecutará la aplicación. Puede hacerlo de una de las maneras siguientes:

Cambiar la configuración regional del sistema operativo.

En la aplicación, agregue el código siguiente 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

Sugerencias para el uso de LocBaml

Todos los ensamblados dependientes que definen controles personalizados se deben copiar en el directorio local de LocBaml o instalarse en la GAC (caché global de ensamblados). Esto es necesario porque la API de localización debe tener acceso a los ensamblados dependientes cuando lee el XAML binario (BAML).
Si el ensamblado principal está firmado, la DLL de recursos generada también debe estar firmada para que se pueda cargar.
La versión de la DLL de recursos localizados debe estar sincronizada con el ensamblado principal.

Compartir a través de