Authors

Olivier GREGOIRE

Versions

 

Version

Date

Object

1

12/12/2006

Document original

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Index

 

Introduction. 3

Creation de ressources. 3

Localiser le projet librairie. 4

Ajouter des données aux ressources. 5

Comprendre le nom des assemblies satellites. 6

Manipuler les ressources dans le code. 6

Ajouter des cultures en dehors de l’IDE.. 9

Création d’un fichier ressources. 9

Création d’un assembly satellite. 10

Annexes. 11

Sources du projet11

Nommer les cultures. 11

Ressources web. 11

 

 

Introduction

 

Le Framework.NET utilise principalement deux processus pour implémenter plusieurs langues dans une application : la globalisation et la localisation.

La globalisation permet de gérer le format monétaire, le format d’horodatage, etc.… en fonction de la langue courante du système. La localisation permet au programmeur d’implémenter plusieurs langues dans une application.

La localisation qui nous intéresse ici permet de manipuler des données personnalisées et des ressources pour une culture et un langage spécifique.

 

Ce document développe la marche à suivre pour créer des assemblies satellites et comment les utiliser dans un assembly principal (exécutable ou librairie). Cette création d’assemblies satellites peut être gérée depuis l’interface Visual Studio mais également séparément du processus de compilation. L’intérêt est de pouvoir dans un premier temps créer facilement des données associées à une culture puis importer de nouvelles langues sans recompiler le projet.

 

 

 

Creation de ressources

 

Les fichiers resources peuvent être manipulés sous trois formes différentes :

 

 

Sous visual studio il est très facile d’incorporer un fichier Xml (.resx) à son projet, nous verrons par la suite l’utilitaire dédié à la manipulation de ces fichiers.

 

Création de l’exemple :

 

Pour comprendre la manipulation de ces données nous allons créer une solution exemple. Nous partirons d’une solution « ExempleLocalisation » comprenant un projet de type libraire de classes et un projet qui va utiliser cette libraire, un projet de type console. Dans cette solution, la librairie sera localisée, et le projet console permettra de jongler entre les cultures pour manipuler la librairie.

 

 

 

Localiser le projet librairie

 

Pour inclure un fichier ressource dans l’IDE, il faut cliquer-droit sur le projet librairie, sélectionner « Ajouter » puis « Ajouter un nouvel élément », la fenêtre suivante apparaît :

 

 

Sélectionner en bas de la liste « Fichier de ressources », et le nommer « Resource.resx ». Le fichier créé est inclus dans le projet, il sera la première étape de la localisation. En effet Visual studio créera automatiquement un assembly satellite à la compilation. Ce fichier constitue la base, il représente la culture neutre, culture qui sera appliquée par défaut si une culture spécifique n’est pas trouvée.

 

Création d’une culture spécifique

 

Pour ajouter de nouvelles cultures, par exemple la culture française et anglaise, il suffit de répéter l’opération en nommant les fichiers de la façon suivante :

 

 

Les fichiers de chaque culture doivent respecter la nomenclature suivante :

 

 

Pour plus d’informations sur la nomenclature des cultures, consulter les annexes.

 

Attention ! La localisation d’une application est basée sur le nom des ressources, il est donc nécessaire de respecter la casse, la nomenclature et le nom des ressources pour pouvoir utiliser les assemblies satellites.

 

Il est intéressant de remarquer que même sans intégrer une seule donnée dans les fichiers ressources, la compilation provoque la création de dossiers nommés comme la culture dans le répertoire de destination comme le montre la structure suivante :

 

 

Dans chaque répertoire destination, l’IDE crée des dossiers nommés comme la culture qui contiennent les assemblies satellites. Cette structure sera toujours respectée.

 

 

 

Ajouter des données aux ressources

 

Lors de l’ajout d’un fichier ressource l’IDE présente une interface suivante pour ajouter des données :

 

 

La façon la plus simple de rajouter des données est donc d’écrire ligne par ligne une paire name-value (dans notre cas d’utilisation nous n’avons pas besoin de définir des commentaires ou un type).

 

Dans notre cas, et pour toutes les ressources nous nous bornerons à ajouter deux lignes associant un chiffre à un libellé faisant référence à la culture comme suit :

 

 

 

Une fois cette opération effectuée votre application est localisée. Il ne reste plus qu’à manipuler le code pour tirer parti de ces données. Mais il convient de comprendre le mécanisme des noms d’assemblies avant cette étape.

 

Comprendre le nom des assemblies satellites

 

Comme nous l’avons vu précédemment, les noms des ressources et des assemblies satellites est très important.

 

Pour mieux comprendre, nous avons crée par l’IDE trois fichiers ressources :

 

 

En sortie, nous avons l’assembly principal et deux assemblies satellites situés dans des sous-dossiers. L’assembly correspondant à la culture neutre est inclus dans l’assembly principal.

 

En utilisant en ligne de commande l’utilitaire « ildasm.exe » (décompilateur) , on peut voir que ces fichiers ressources ont été renommés de la façon suivante :

 

 

La nomenclature est donc :

 

[Nom de l’application].[Nom de la ressource].[Nom de la culture].resources

 

Cette nomenclature permet d’accéder aux données dans le code. Comme vous pouvez le voir la seule exception est la culture neutre qui n’a pas de nom de culture, assez logiquement.

 

 

Manipuler les ressources dans le code

 

La première étape pour manipuler les ressources est d’ajouter les références suivantes dans le code de la librairie de classe :

 

using System.Resources;

using System.Reflection;

 

 

Notre classe va uniquement comprendre un constructeur vide et une méthode publique qui va prendre en argument une chaîne et retourner une chaîne correspondante. On comprend que l’intérêt de cette méthode est de retourner un libellé localisé correspondant à un code, comme dans les fichiers ressources.

 

Pour poursuivre sur notre exemple votre code doit donc ressembler au suivant :

 

 

Pour lire la ressource, nous devons créer une instance de la classe ResourceManager avec le nom de base et une assembly.

 

Le nom de base correspond à :  [Nom de l’application].[Nom de la ressource], ici TestLibrary.Resource.

Et on récupère simplement l’assembly en cours d’exécution par l’instruction Assembly.GetExecutingAssembly().

 

 

En fonction de la culture de l’assembly en cours d’exécution, la méthode GetString() renverra le libellé correspondant à cette culture spécifique. La classe ResourceManager se charge de trouver l’assembly satellite correspondant à la culture, et charge la culture neutre si elle ne trouve pas le bon assembly.

 

 

Si vous utilisez la librairie à cette étape du développement dans la console, vous obtiendrez toujours les libellés correspondant à la culture du système. Il convient maintenant de manipuler le code pour changer la culture.

 

La console doit manipuler la librairie précédemment crée et prendre deux arguments :

 

·         La culture spécifique

·         Le code à traduire

 

Le code de votre classe doit donc ressembler à ceci :

 

 

Il faut remarquer en premier lieu les référence suivantes :

 

using System.Threading;

using System.Globalization;

 

Ces deux namespaces permettent respectivement de manipuler le thread courant et les cultures. Pour changer la culture du thread courant il suffit alors de la ligne suivante :

 

Thread.CurrentThread.CurrentUICulture = new CultureInfo(sCulture);

Par la suite, l’utilisation de la librairie crée au-dessus permettra de récupérer des libellés spécifiques à une culture.

 

Pour cela il suffit de lancer la console en ligne de commande :

 

L’appel « TestConsole.exe en-GB 1 » donnera : « value 1 culture en-GB »

 

 

Ajouter des cultures en dehors de l’IDE

 

La structure de dossier de sortie du projet console créé par Visual studio est la suivante :

 

 

Nous avons vu que pour utiliser une nouvelle culture il fallait incorporer un fichier ressource dans le projet puis recompiler. Cette méthode sous-entend que le développeur fait office de traducteur. Ce qui n’est pas très indiqué ou peut être très fastidieux. Nous allons donc voir les étapes à suivre pour créer un assembly satellite utilisable par la console sans recompiler la solution.

 

·         Créer un fichier ressources à partir d’un fichier texte

·         Créer un assembly satellite à partir de la ressource

·         Déployer le résultat

 

Création d’un fichier ressources

 

Le framework fournit un utilitaire en ligne de commande qui s’appelle resgen.exe

 

L'outil Resource File Generator Tool (Générateur de fichiers de ressources) convertit les fichiers .txt et .resx (format de ressource XML) en fichiers .resources binaires CLR pouvant être incorporés à un exécutable binaire runtime ou compilés dans des assemblys satellites. Pour obtenir plus d’informations consulter les liens en annexes.

 

Resgen.exe effectue les conversions suivantes :

 

 

Dans notre cas, imaginons que nous avons en source un fichier RessourcesRusses.txt contenant les informations relatives à la culture ru-RU (russe)

 

Le contenu du fichier doit être formaté de la façon suivante :

 

# Utilisez # au début d'une ligne pour un caractère de commentaire.

[clé1]=[valeur1]

[clé2]=[valeur2]

 

La ligne de commande s’utilise de la façon suivante :

ResGen inputFile.ext [outputFile.ext]

 

Dans notre cas, pour créer le fichier ressources, la ligne serait :

ResGen RessourcesRusses.txt Resource.ru-RU.resources

 

Notre fichier binaire .resources existe maintenant. Il faut l’intégrer à un assembly satellite.

 

Création d’un assembly satellite

 

L’outil fournit par le framework pour créer des assembly s’appelle « Assembly Linker » : al.exe.

 

Assembly Linker génère un fichier avec un manifeste de l'assembly à partir d'un ou de plusieurs fichiers qui sont soit des modules, soit des fichiers de ressources. Dans notre exemple nous allons donc l’utiliser avec un fichier .resources. La commande ressemble à  la suivante :

 

Al.exe /t:lib /embed:Resource.ru-Ru.resources,TestLibrary.Resource.ru-RU.resources /culture:ru-RU /out:TestLibrary.resources.dll

 

L’explication de cette ligne est la suivante

 

Le fichier TestLibrary.resources.dll est maintenant créé. Il reste la dernière étape pour le déployer.

 

Déployer un assembly satellite

 

Cette étape est la plus simple. Il suffit de copier le satellite précedemment créé dans le dossier ou se situe l’exécutable, dans un dossier portant exactement le même nom que la culture.

 

Dans notre cas le dossier aurait cette allure :

 

 

la console est maintenant prête à focntionner avec trois cultures spécifiques :

 

 

Pour ajouter différentes cultures, le process peut se dérouler en dehors de tout environnement de développement. Il suffira d’automatiser dans un batch le traitement des fichiers textes.

 

Annexes

 

Sources du projet

 

Le projet exemple que nous avons développé tout au long de ce document est disponible dans le zip Exemple.zip, il contient la solution et le fichier texte de ressource.

 

Nommer les cultures

 

Le nom des cultures respecte la norme RFC 1766 au format « <languagecode2>-<country/regioncode2> », où <languagecode2> est un code de deux lettres minuscules dérivé de ISO 639-1 et <country/regioncode2> est un code de deux lettres majuscules dérivé de ISO 3166. Par exemple, « en-US » (Anglais - États-Unis) est une culture spécifique.

 

 

Ressources web

 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpcondesigningglobalapplications.asp

 

http://msdn.microsoft.com/library/FRE/cpguide/html/cpconcreatingusingresources.asp