Procedura: Localizzare un'applicazione

2025-05-07

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

Annotazioni

LocBaml non è un'applicazione pronta per la produzione. Viene presentato come esempio che usa alcune API di localizzazione e illustra come scrivere uno strumento di localizzazione.

Informazioni generali

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 l'estensione .resources.dll) per contenere le risorse del linguaggio neutre. Il file di progetto nell'esempio HelloApp è HelloApp.csproj. In tale file si troverà il linguaggio di sviluppo identificato come segue:

<UICulture>en-US</UICulture>
Aggiungere gli Uids ai file XAML. Gli uids vengono usati per tenere traccia delle modifiche apportate ai file e per identificare gli elementi che devono essere tradotti. 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 di updateuid, i file dovrebbero 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.
Dalla riga di comando eseguire il file di progetto (locbaml.csproj) per compilare lo strumento:

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` o `-p`	Analizza file Baml, risorse o DLL per generare un file .csv o .txt.
`generate` o `-g`	Genera un file binario localizzato utilizzando un file tradotto.
`out` o `-o` {filedirectory}	Nome file di output.
`culture` o `-cul` {culture}	Impostazioni della localizzazione 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à.

Annotazioni

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

Usare LocBaml per analizzare un file

Dopo aver creato lo strumento LocBaml, è possibile usarlo per analizzare HelloApp.resources.dll per estrarre il contenuto di testo 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 di assembly satellite e archiviare l'output come file .csv, usare il comando seguente:

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

Annotazioni

Se il file di input, HelloApp.resources.dll, non si trova nella stessa directory di LocBaml.exe spostare uno dei file in modo che entrambi i file si trovino nella stessa directory.

Quando si esegue LocBaml per analizzare i file, l'output è costituito da sette campi delimitati da virgole (file.csv) o schede (.txt file). Di seguito viene illustrato il file di .csv analizzato per il HelloApp.resources.dll:

File di .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,,Ciao Mondo
HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Addio Mondo

I sette campi sono:

Nome BAML. Nome della risorsa BAML in relazione all'assembly satellite della lingua di origine.
Chiave risorsa. Identificatore di risorsa localizzato.
Categoria. Tipo di valore. Vedere Attributi e commenti di localizzazione.
Leggibilità. Indica se il valore può essere letto da un localizzatore. Vedere Attributi e commenti di localizzazione.
Modificabilità. Indica se il valore può essere modificato da un localizzatore. Vedere Attributi e commenti di localizzazione.
Commenti. Descrizione aggiuntiva del valore per determinare la modalità di localizzazione di un valore. Vedere Attributi e commenti di localizzazione.
Valore. Valore di testo da tradurre nella cultura desiderata.

Nella tabella seguente viene illustrato 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	Falso	Falso	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	Nessuno	Vero	Vero	Salve, mondo
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Nessuno	Vero	Vero	Addio mondo

Si noti che tutti i valori per il campo Commenti non contengono valori; se un campo non ha un valore, è vuoto. Si noti inoltre che l'elemento nella prima riga non è leggibile né modificabile e ha "Ignore" come valore Category , che indica che il valore non è localizzabile.

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

Tradurre il contenuto localizzabile

Usare qualsiasi strumento disponibile per tradurre il contenuto estratto. Un buon modo per eseguire questa operazione consiste nel scrivere le risorse in un file .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 dall'analisi HelloApp.resources.dll con LocBaml è stato convertito e deve essere unito di nuovo all'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 la cultura come en-US (/cul:en-US)

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

Annotazioni

Se il file di input, Hello.csv, non si trova nella stessa directory dell'eseguibile, LocBaml.exe, spostare uno dei file in modo che entrambi i file si trovino nella stessa directory.
Sostituire il file HelloApp.resources.dll precedente nella directory C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll con il file HelloApp.resources.dll appena creato.
"Hello World" e "Goodbye World" dovrebbero ora essere tradotti nell'applicazione.
Per tradurre in una cultura diversa, usa la cultura della lingua in cui stai traducendo. L'esempio seguente illustra come tradurre in 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, crea una nuova cartella specifica della cultura per ospitare il nuovo assembly satellite. Per il francese-canadese, la cartella è fr-CA.
Copiare l'assembly satellite generato nella nuova cartella.

Per testare il nuovo assembly satellite, dovresti modificare la cultura sotto cui l'applicazione funzionerà. È possibile eseguire questa operazione in uno dei due modi seguenti:

Modificare le impostazioni internazionali del sistema operativo.

Nell'applicazione aggiungere il codice seguente 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

Suggerimenti per l'uso di LocBaml

Tutti gli assembly dipendenti che definiscono controlli personalizzati devono essere copiati nella directory locale di LocBaml o installati nella GAC. 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, è necessario firmare anche la DLL della risorsa generata affinché venga caricata.
La versione della DLL delle risorse localizzate deve essere sincronizzata con l'assembly principale.

Condividi tramite