Procedura: Localizzare un'applicazione

Articolo
10/18/2023

Questa esercitazione spiega come creare un'applicazione localizzata usando lo strumento LocBaml.

Nota

Lo strumento LocBaml non è un'applicazione di produzione. Viene presentato come esempio in cui vengono usate alcune delle API di localizzazione e illustra come scrivere uno strumento di localizzazione.

Panoramica

Questo articolo offre un approccio dettagliato alla localizzazione di un'applicazione. Prima di tutto, si prepara l'applicazione in modo che il testo che verrà tradotto possa essere estratto. Dopo la traduzione del testo, unire il testo tradotto in una nuova copia dell'applicazione originale.

Creare un'applicazione di esempio

In questo passaggio si prepara l'app per la localizzazione. Negli esempi di Windows Presentation Foundation (WPF) viene fornito un esempio HelloApp che verrà usato per gli esempi di codice in questa discussione. Per usare questo esempio, scaricare i file XAML (Extensible Application Markup Language) dall'esempio di strumento LocBaml.

Sviluppare l'applicazione fino al punto in cui si vuole iniziare la localizzazione.
Specificare il linguaggio di sviluppo nel file di progetto in modo che MSBuild generi un assembly principale e un assembly satellite (un file con estensione resources.dll) per contenere le risorse del linguaggio neutre. Il file di progetto nell'esempio HelloApp è HelloApp.csproj. In questo file la lingua di sviluppo viene identificata come segue:

<UICulture>en-US</UICulture>
Aggiungere uids ai file XAML. Gli UID vengono usati per rilevare le modifiche apportate ai file e per identificare gli elementi da convertire. Per aggiungere uids ai file, eseguire updateuid nel file di progetto:

msbuild -t:updateuid helloapp.csproj

Per verificare che non siano presenti uid mancanti o duplicati, eseguire checkuid:

msbuild -t:checkuid helloapp.csproj

Dopo l'esecuzione updateuiddi , i file devono contenere uids. Ad esempio, nel file Pane1.xaml di HelloApp è necessario trovare quanto segue:
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

Creare l'assembly satellite delle risorse in linguaggio neutro

Dopo aver configurato l'applicazione per generare un assembly satellite di risorse in linguaggio neutro, si compila l'applicazione. In questo modo viene generato l'assembly principale dell'applicazione e l'assembly satellite delle risorse in linguaggio neutro richiesto da LocBaml per la localizzazione.

Per compilare l'applicazione:

Compilare HelloApp per creare una libreria a collegamento dinamico (DLL):

msbuild helloapp.csproj
L'assembly principale dell'applicazione appena creato, HelloApp.exe, viene creato nella cartella seguente: C:\HelloApp\Bin\Debug
L'assembly satellite delle risorse indipendenti appena creato, HelloApp.resources.dll, viene creato nella cartella seguente: C:\HelloApp\Bin\Debug\en-US

Compilare lo strumento LocBaml

Tutti i file necessari per compilare LocBaml si trovano negli esempi WPF. Scaricare i file C# dall'esempio di strumento LocBaml.
Eseguire il file di progetto (LocBaml.csproj) per compilare lo strumento dalla riga di comando:

msbuild locbaml.csproj
Passare alla directory Bin\Release per trovare il file eseguibile appena creato (locbaml.exe). Esempio: C:\LocBaml\Bin\Release\locbaml.exe

Le opzioni che è possibile specificare quando si esegue LocBaml sono le seguenti.

Opzione	Descrizione
`parse` oppure `-p`	Analizza i file Baml, resources o DLL per generare un file con estensione csv o txt.
`generate` oppure `-g`	Genera un file binario localizzato utilizzando un file tradotto.
`out` o `-o` {filedirectory]	Nome file di output.
`culture` o `-cul` {culture]	Impostazioni locali degli assembly di output.
`translation` o `-trans` {translation.csv]	File tradotto o localizzato.
`asmpath` o `-asmpath` {filedirectory]	Se il codice XAML contiene controlli personalizzati, devi fornire l'oggetto `asmpath` all'assembly di controllo personalizzato.
`nologo`	Non visualizza alcun logo o informazioni sul copyright.
`verbose`	Visualizza informazioni dettagliate sulla modalità.

Nota

Se è necessario un elenco delle opzioni quando si esegue lo strumento, immettere LocBaml.exe e quindi premere INVIO.

Usare LocBaml per analizzare un file

Ora che è stato creato lo strumento LocBaml, è possibile usarlo per analizzare HelloApp.resources.dll ed estrarre il contenuto testuale che verrà localizzato.

Copiare LocBaml.exe nella cartella bin\debug dell'applicazione in cui è stato creato l'assembly principale dell'applicazione.
Per analizzare il file dell'assembly satellite e archiviare l'output come file CSV, usare il comando seguente:

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

Nota

Se il file di input, HelloApp.resources.dll, non è nella stessa directory di LocBaml.exe, spostare uno dei file in modo che entrambi siano nella stessa directory.

Quando si esegue LocBaml per analizzare i file, l'output è costituito da sette campi delimitati da virgole (file CSV) o da tabulazioni (file TXT). Di seguito viene visualizzato il file CSV analizzato per HelloApp.resources.dll:

File csv analizzato
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

I campi di sette sono:

Nome BAML. Il nome della risorsa BAML rispetto all'assembly satellite per la lingua di origine.
Chiave di risorsa. L'identificatore della risorsa localizzata.
Categoria. Tipo di valore. Vedere Attributi e commenti di localizzazione.
Leggibilità. Se il valore può essere letto da un localizzatore. Vedere Attributi e commenti di localizzazione.
Modifiability. Se il valore può essere modificato da un localizzatore. Vedere Attributi e commenti di localizzazione.
Commenti. Descrizione aggiuntiva del valore per determinarne la modalità di localizzazione. Vedere Attributi e commenti di localizzazione.
Valore. Il valore di testo da convertire nelle impostazioni cultura desiderate.

La tabella seguente mostra come viene eseguito il mapping di questi campi ai valori delimitati del file CSV:

Nome BAML	Chiave risorsa	Categoria	Leggibilità	Modificabilità	Valore
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Ignora	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

Tutti i valori nel campo Commenti non contengono valori. Se un campo non contiene valori, è vuoto. Inoltre, l'elemento nella prima riga non è né leggibile né modificabile e ha "Ignora" come valore del campo Categoria, il che indica che il valore non è localizzabile.

Per facilitare l'individuazione degli elementi localizzabili nei file analizzati, in particolare nei file di grandi dimensioni, è possibile ordinare o filtrare gli elementi per Categoria, Leggibilità e Modificabilità. Ad esempio, è possibile escludere i valori non leggibili e non modificabili.

Tradurre il contenuto localizzabile

Usare gli strumenti disponibili per convertire il contenuto estratto. Un buon modo per eseguire questa operazione consiste nel scrivere le risorse in un file con estensione csv e visualizzarle in Microsoft Excel, apportando modifiche alla traduzione all'ultima colonna (valore).

Usare LocBaml per generare un nuovo file .resources.dll

Il contenuto identificato analizzando HelloApp.resources.dll con LocBaml è stato convertito e deve essere reinserito nell'applicazione originale. Usare l'opzione generate o -g per generare un nuovo file .resources.dll.

Usare la sintassi seguente per generare un nuovo file HelloApp.resources.dll. Contrassegnare le impostazioni cultura come en-US (/cul:en-US).

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

Nota

Se il file di input Hello.csv non è presente nella stessa directory del file eseguibile LocBaml.exe, spostare uno dei file in modo che entrambi siano nella stessa directory.
Sostituire il file HelloApp.resources.dll precedente nel file C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll con il file HelloApp.resources.dll appena creato.
Ora "Hello World" e "Goodbye World" possono essere convertiti nell'applicazione.
Per eseguire la conversione in una lingua diversa, usare le impostazioni cultura della lingua in cui si sta eseguendo la conversione. L'esempio seguente mostra come eseguire la conversione in lingua francese canadese:

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
Nello stesso assembly dell'assembly principale dell'applicazione, creare una nuova cartella specifica per le impostazioni cultura dove ospitare il nuovo assembly satellite. Per la lingua francese canadese, la cartella sarà fr-CA.
Copiare l'assembly satellite generato nella nuova cartella.

Per testare il nuovo assembly satellite, è necessario modificare le impostazioni cultura con cui verrà eseguita l'applicazione. È possibile effettuare questa operazione in uno dei due modi seguenti:

Modificare le impostazioni internazionali del sistema operativo.

Aggiungere il codice seguente al file App.xaml.cs nell'applicazione:

<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

Suggerimenti per l'uso di LocBaml

Tutti gli assembly dipendenti che definiscono i controlli personalizzati devono essere copiati nella directory locale di LocBaml o installati in Global Assembly Cache. Questa operazione è necessaria perché l'API di localizzazione deve avere accesso agli assembly dipendenti quando legge il codice XAML binario (BAML).
Se l'assembly principale è firmato, anche la DLL di risorse generata deve essere firmata per poter essere caricata.
La versione della DLL di risorsa localizzata deve essere sincronizzata con l'assembly principale.

Condividi tramite