Guide pratique pour localiser une application

Article
01/30/2025

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

Note

L’outil LocBaml n’est pas une application prête pour la production. Il est présenté sous la forme d’un exemple qui utilise certaines API de localisation et illustre la façon dont vous pouvez écrire un outil de localisation.

Aperçu

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 souhaitez 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 projet dans l’exemple HelloApp est 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 uids sont utilisés pour suivre les modifications apportées aux fichiers et identifier les éléments qui doivent être traduits. Pour ajouter uids à vos fichiers, exécutez updateuid sur votre fichier projet :

msbuild -t:updateuid helloapp.csproj

Pour vérifier que vous ne disposez pas de Uids manquants ou dupliqués, exécutez checkuid:

msbuild -t:checkuid helloapp.csproj

Après avoir exécuté 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 de ressources de langage neutre

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 de langage neutre 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 .
À partir de la ligne de commande, exécutez le fichier 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` {répertoire de fichiers]	Nom du fichier de sortie.
`culture` ou `-cul` {culture]	Localisation des assemblages de sortie.
`translation` ou `-trans` {translation.csv]	Fichier traduit ou localisé.
`asmpath` ou `-asmpath` {répertoire de fichiers]	Si votre code XAML contient des contrôles personnalisés, vous devez fournir le `asmpath` à l'assembly de contrôles personnalisés.
`nologo`	Affiche aucun logo ni aucune information sur le droit d’auteur.
`verbose`	Affiche les informations en mode détaillé.

Note

Si vous avez besoin d’une liste des options lorsque vous exécutez l’outil, entrez LocBaml.exe, puis appuyez 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 pour extraire le contenu texte qui sera localisé.

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

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

Note

Si le fichier d’entrée, HelloApp.resources.dll, n’est pas dans le même répertoire que LocBaml.exe déplacer l’un des fichiers afin que les deux fichiers se trouvent dans le même répertoire.

Lorsque vous exécutez LocBaml pour analyser des fichiers, la sortie se compose de sept champs délimités par des virgules (fichiers.csv) ou des onglets (fichiers.txt). L’exemple suivant montre le fichier de .csv analysé pour l'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 :

Nom BAML. Nom de la ressource BAML par rapport à l'assembly satellite de langage source.
Clé de la ressource. Identificateur de ressource localisé.
Catégorie. Le type de valeur. Consultez Attributs de localisation et commentaires.
Lisibilité. Indique si la valeur peut être lue par un localiseur. Consultez Attributs de localisation et commentaires.
Caractère modifiable. Indique si la valeur peut être modifiée par un localiseur. Consultez Attributs de localisation et commentaires.
Commentaires. Description supplémentaire de la valeur pour déterminer comment une valeur est localisée. Consultez Attributs de localisation et commentaires.
Valeur. Valeur de texte à traduire dans la culture souhaitée.

Le tableau suivant montre comment ces champs correspondent aux valeurs délimitées du fichier .csv :

Nom BAML	Clé de la ressource	Catégorie	Lisibilité	Modifiabilité	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	Salut tout le monde
HelloApp.g.en-US.resources:window1.baml	Text2 : System.Windows.Controls.TextBlock.$Content	Aucun	VRAI	VRAI	Au revoir le monde

Notez que toutes les valeurs du champ commentaires ne contiennent aucune valeur ; si un champ n’a pas de valeur, il est vide. Notez également que l’élément de la première ligne n’est ni lisible ni modifiable, et qu’il a « Ignorer » comme valeur Catégorie, qui indique que la valeur n’est pas localisable.

Pour faciliter la découverte d’éléments localisables dans des fichiers analysés, en particulier dans les fichiers volumineux, vous pouvez trier ou filtrer les éléments par Catégorie, de lisibilité et modifiabilité. Par exemple, vous pouvez filtrer les valeurs non lisibles et non modifiables.

Traduire le contenu localisable

Utilisez n’importe quel outil que vous avez disponible 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 identifié par l’analyse HelloApp.resources.dll avec LocBaml a été traduit et doit être fusionné dans l’application d’origine. Utilisez l’option generate ou -g 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

Note

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 fichiers afin que les deux fichiers 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 vers une autre culture, utilisez la culture de la langue vers laquelle vous effectuez la traduction. L’exemple suivant montre comment traduire en français-canadien :

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 effectuer cette opération de deux manières :

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

Conseils 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 ressource localisée doit être synchronisée avec l’assembly principal.

Partager via