Guide pratique pour localiser une application

Article
10/18/2023

Ce didacticiel explique comment créer une application localisée à l'aide de l'outil LocBaml.

Remarque

L'outil LocBaml n'est pas une application prête pour la production. Il est présenté comme un exemple qui fait appel à un certain nombre d'API de localisation et montre comment vous pouvez écrire un outil de localisation.

Vue d’ensemble

Cet article vous donne une approche pas à pas de la localisation d’une application. Tout d’abord, vous préparez votre application afin que le texte qui sera traduit puisse être extrait. Une fois le texte traduit, vous fusionnez le texte traduit dans une nouvelle copie de l’application d’origine.

Créer un exemple d’application

Dans cette étape, vous préparez votre application pour la localisation. Dans les exemples WINDOWS Presentation Foundation (WPF), un exemple HelloApp est fourni qui sera utilisé pour les exemples de code de cette discussion. Si vous souhaitez utiliser cet exemple, téléchargez les fichiers XAML (Extensible Application Markup Language) à partir de l’exemple d’outil LocBaml.

Développez votre application jusqu'au point où vous voulez démarrer la localisation.
Spécifiez le langage de développement dans le fichier projet afin que MSBuild génère un assembly principal et un assembly satellite (fichier avec l’extension .resources.dll) pour contenir les ressources linguistiques neutres. Le fichier de projet de l'exemple HelloApp s'intitule HelloApp.csproj. Dans ce fichier, vous trouverez le langage de développement identifié comme suit :

<UICulture>en-US</UICulture>
Ajoutez Uids à vos fichiers XAML. Les UID permettent de suivre les modifications apportées aux fichiers et d'identifier les éléments qui doivent être traduits. Pour ajouter Uids à vos fichiers, exécutez-le updateuid sur votre fichier projet :

msbuild -t:updateuid helloapp.csproj

Pour vérifier que vous n’avez pas d’uids manquants ou dupliqués, exécutez checkuid:

msbuild -t:checkuid helloapp.csproj

Après l’exécution updateuid, vos fichiers doivent contenir des uids. Par exemple, dans le fichier Pane1.xaml de HelloApp, vous devez trouver les éléments suivants :
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

Créer l’assembly satellite des ressources neutres

Une fois l’application configurée pour générer un assembly satellite de ressources en langage neutre, vous générez l’application. Cela génère l’assembly d’application principal ainsi que l’assembly satellite de ressources en langage neutre requis par LocBaml pour la localisation.

Pour générer l’application :

Compilez HelloApp pour créer une bibliothèque de liens dynamiques (DLL) :

msbuild helloapp.csproj
L’assembly d’application principal nouvellement créé, HelloApp.exe, est créé dans le dossier suivant : C :\HelloApp\Bin\Debug
L’assembly satellite de ressources neutres nouvellement créé, HelloApp.resources.dll, est créé dans le dossier suivant : C :\HelloApp\Bin\Debug\en-US

Générer l’outil LocBaml

Tous les fichiers nécessaires pour générer LocBaml se trouvent dans les exemples WPF. Téléchargez les fichiers C# à partir de l’exemple d’outil LocBaml.
Dans la ligne de commande, exécutez le fichier de projet (locbaml.csproj) pour générer l'outil :

msbuild locbaml.csproj
Accédez au répertoire Bin\Release pour rechercher le fichier exécutable nouvellement créé (locbaml.exe). Exemple : C :\LocBaml\Bin\Release\locbaml.exe

Les options que vous pouvez spécifier lorsque vous exécutez LocBaml sont les suivantes.

Option	Description
`parse` ou `-p`	Analyse les fichiers Baml, ressources ou DLL pour générer un fichier .csv ou .txt.
`generate` ou `-g`	Génère un fichier binaire localisé à l’aide d’un fichier traduit.
`out` ou `-o` {filedirectory]	Nom du fichier de sortie.
`culture` ou `-cul` {culture]	Paramètres régionaux des assemblys de sortie.
`translation` ou `-trans` {translation.csv]	Fichier traduit ou localisé.
`asmpath` ou `-asmpath` {filedirectory]	Si votre code XAML contient des contrôles personnalisés, vous devez fournir l’assembly `asmpath` de contrôle personnalisé.
`nologo`	Affiche aucun logo ni aucune information sur le droit d’auteur.
`verbose`	Affiche les informations en mode détaillé.

Remarque

Si vous avez besoin d’une liste des options lorsque vous exécutez l’outil, entrez, puis appuyez LocBaml.exe sur Entrée.

Utiliser LocBaml pour analyser un fichier

Maintenant que vous avez créé l'outil LocBaml, vous êtes prêt à l'utiliser pour analyser HelloApp.resources.dll et ainsi extraire le texte qui sera localisé.

Copiez LocBaml.exe dans le dossier bin\debug de votre application, là où l'assembly d'application principal a été créé.
Pour analyser le fichier d'assembly satellite et stocker la sortie sous forme de fichier .csv, utilisez la commande suivante :

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

Remarque

Si le fichier d'entrée, HelloApp.resources.dll, n'est pas dans le même répertoire que LocBaml.exe, déplacez l'un des deux fichiers de telle sorte qu'ils se trouvent dans le même répertoire.

Quand vous exécutez LocBaml pour analyser les fichiers, la sortie se compose de sept champs délimités par des virgules (fichiers .csv) ou des tabulations (fichiers .txt). Voici le fichier .csv analysé pour HelloApp.resources.dll :

Fichier .csv analysé
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

Les sept champs sont les suivants :

BAML Name. Nom de la ressource BAML par rapport à l'assembly satellite de langage source.
Resource Key. Identificateur de la ressource localisée.
Catégorie : Type de valeur. Consultez Attributs et commentaires de localisation.
Readability. Indique si la valeur peut être lue par un localisateur. Consultez Attributs et commentaires de localisation.
Modifiabilité : Indique si la valeur peut être modifiée par un localisateur. Consultez Attributs et commentaires de localisation.
Commentaires. Description supplémentaire de la valeur pour aider à déterminer comment une valeur est localisée. Consultez Attributs et commentaires de localisation.
Valeur. valeur de texte à traduire dans la culture souhaitée.

Le tableau suivant montre comment ces champs sont mappés par rapport aux valeurs délimitées du fichier .csv :

BAML name	Ressources clés	Catégorie	Readability	Modifiability	Valeur
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	Ignorer	FAUX	FAUX	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	Aucun	VRAI	VRAI	Hello World
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	Aucun	VRAI	VRAI	Goodbye World

Notez que le champ Comments ne contient aucune valeur ; si un champ n’a pas de valeur, il est vide. De même, vous remarquerez que l’élément de la première ligne n’est ni lisible ni modifiable et que le champ Category a la valeur « Ignore », ce qui indique que la valeur n’est pas localisable.

Pour faciliter la découverte des éléments localisables dans les fichiers analysés, en particulier dans les fichiers volumineux, vous pouvez trier ou filtrer les éléments en fonction des champs Category, Readability et Modifiability. Par exemple, vous pouvez filtrer les valeurs illisibles et non modifiables.

Traduire le contenu localisable

Utilisez n'importe quel outil à votre disposition pour traduire le contenu extrait. Pour ce faire, il est judicieux d’écrire les ressources dans un fichier .csv et de les afficher dans Microsoft Excel, en apportant des modifications de traduction à la dernière colonne (valeur).

Utiliser LocBaml pour générer un nouveau fichier .resources.dll

Le contenu qui a été identifié en analysant HelloApp.resources.dll avec LocBaml a été traduit et doit être fusionné dans l'application d'origine. Utilisez la ou -g l’option generate pour générer un nouveau fichier .resources.dll.

Utilisez la syntaxe suivante pour générer un nouveau fichier HelloApp.resources.dll. Indiquez la culture en-US (/cul:en-US).

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

Remarque

Si le fichier d'entrée, Hello.csv, n'est pas dans le même répertoire que l'exécutable, LocBaml.exe, déplacez l'un des deux fichiers de telle sorte qu'ils se trouvent dans le même répertoire.
Remplacez l’ancien fichier HelloApp.resources.dll dans le répertoire C :\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll par votre fichier HelloApp.resources.dll nouvellement créé.
« Hello World » et « Goodbye World » doivent maintenant être traduits dans votre application.
Pour traduire dans une autre culture, utilisez celle qui correspond à la langue d'arrivée de la traduction. L'exemple suivant montre comment traduire en français du Canada :

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
Dans le même assembly que l'assembly d'application principal, créez un dossier propre à la culture pour héberger le nouvel assembly satellite. Pour le français du Canada, le dossier s'intitulerait fr-CA.
Copiez l'assembly satellite généré dans le nouveau dossier.

Pour tester le nouvel assembly satellite, vous devez modifier la culture sous laquelle votre application s'exécutera. Vous pouvez le faire de deux façons :

Modifiez les paramètres régionaux de votre système d’exploitation.

Dans votre application, ajoutez le code suivant à 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

Astuces pour l’utilisation de LocBaml

Tous les assemblys dépendants qui définissent des contrôles personnalisés doivent être copiés dans le répertoire local de LocBaml ou installés dans le GAC. Cela est nécessaire, car l’API de localisation doit avoir accès aux assemblys dépendants lorsqu’elle lit le code XAML binaire (BAML).
Si l'assembly principal est signé, la DLL de ressources générée doit l'être également pour pouvoir être chargée.
La version de la DLL de ressources localisées doit être synchronisée avec l'assembly principal.