Partager via

Localiser les chaînes dans votre IU et le manifeste du package d’application

  • Article

Pour plus d’informations sur la proposition de valeur de la localisation de votre application SDK d'application Windows, consultez Internationalisation et localisation.

Si vous souhaitez que votre application prenne en charge différentes langues d’affichage et si des opérateurs de chaîne figurent dans votre code, votre balisage XAML ou le manifeste du package d’application, déplacez ces chaînes dans un fichier de ressources (.resw). Vous pouvez ensuite effectuer une copie traduite de ce fichier de ressources pour chaque langue prise en charge par votre application.

Les littéraux de chaîne codés en dur peuvent apparaître dans du code impératif ou dans la balise XAML, par exemple en tant que propriété Texte d’un TextBlock. Ils peuvent également apparaître dans le fichier source du manifeste du package d’application (le Package.appxmanifest fichier), par exemple comme valeur du nom complet sous l’onglet Application du Concepteur de manifeste Visual Studio. Déplacez ces chaînes dans un fichier de ressources (.resw) et remplacez les littéraux de chaîne codés en dur dans votre application et dans votre manifeste par des références à des identificateurs de ressource.

Contrairement aux ressources d’image, où une seule ressource d’image est contenue dans un fichier de ressources d’image, plusieurs ressources de chaîne sont contenues dans un fichier de ressources de chaîne. Un fichier de ressources de chaîne est un fichier de ressources (.resw) et vous créez généralement ce type de fichier de ressources dans un dossier \Strings dans votre projet. Pour plus d’informations sur l’utilisation des qualificateurs dans les noms de vos fichiers de ressources (.resw), consultez Personnaliser vos ressources pour la langue, la mise à l’échelle et d’autres qualificateurs.

Stocker des chaînes dans un fichier de ressources

  1. Définissez la langue par défaut de votre application.

    1. Votre solution étant ouverte dans Visual Studio, ouvrez Package.appxmanifest.
    2. Sous l’onglet Application, vérifiez que la langue par défaut est définie de manière appropriée (par exemple, « en » ou « en-US »). Les étapes restantes supposent que vous avez défini la langue par défaut sur « en-US ».

    Remarque

    Au minimum, vous devez fournir des ressources de chaîne localisées pour cette langue par défaut. Il s’agit des ressources qui seront chargées si aucune meilleure correspondance n’est disponible pour la langue par défaut de l’utilisateur ou les paramètres de langue d’affichage.

  2. Créez un fichier de ressources (.resw) pour la langue par défaut.

    1. Sous le nœud de votre projet, créez un nouveau dossier et nommez-le Strings.
    2. Sous Strings, créez un nouveau sous-dossier et nommez-le en-US.
    3. Sous en-US, créez un fichier de ressources (.resw) (sous les types de fichiers WinUI dans la boîte de dialogue Ajouter un nouvel élément) et vérifiez qu’il est nommé Resources.resw.

    Remarque

    Si vous disposez de fichiers de ressources .NET (.resx) que vous souhaitez porter, consultez Portage du code XAML et de l’IU.

  3. Ouvrez Resources.resw et ajoutez ces ressources de chaîne.

    Strings/en-US/Resources.resw

    Capture d’écran de la table Ajouter une ressource du fichier Strings > E U S > Resources.resw.

    Dans cet exemple, «  Greeting » est un identifiant de ressource de chaîne auquel vous pouvez faire référence à partir de votre balise, comme nous allons l’afficher. Pour l’identifiant « Greeting », une chaîne est fournie pour une propriété Texte et une chaîne est fournie pour une propriété Width. « Greeting.Text » est un exemple d’identifiant de propriété, car il correspond à une propriété d’un élément IU. Vous pouvez également ajouter « Greeting.Foreground » dans la colonne Nom et définir sa valeur sur « Rouge ». L’identifiant « Farewell » est un identificateur de ressource de chaîne simple ; elle n’a pas de sous-propriétés et peut être chargée à partir du code impératif, comme nous allons l’afficher. La colonne Commentaire est un bon endroit pour fournir des instructions spéciales aux traducteurs.

    Dans cet exemple, étant donné que nous avons une entrée d’identifiant de ressource de chaîne simple nommée « Farewell », nous ne pouvons pas également avoir d’identificateurs de propriété basés sur ce même identificateur. Par conséquent, l’ajout de « Farewell.Text » provoquerait une erreur de duplicata lors de la génération Resources.resw.

    Les identifiants de ressource ne respectent pas la casse et doivent être uniques par fichier de ressources. Veillez à utiliser des identifiants de ressources explicites pour fournir un contexte supplémentaire pour les traducteurs. Et ne modifiez pas les identificateurs de ressource une fois les ressources de chaîne envoyées pour la traduction. Les équipes de localisation utilisent l’identifiant de ressource pour suivre les ajouts, les suppressions et les mises à jour dans les ressources. Les modifications apportées aux identificateurs de ressource, également appelées « décalage des identificateurs de ressource », nécessitent la retranscrite des chaînes, car elles apparaissent comme si des chaînes ont été supprimées et d’autres ont été ajoutées.

Reportez-vous à un identifiant de ressource de chaîne à partir de XAML

La directive x:Uid permet d'associer un contrôle ou un autre élément de votre balisage à un identifiant de ressource sous forme de chaîne.

<TextBlock x:Uid="Greeting"/>

Au moment de l’exécution, \Strings\en-US\Resources.resw est chargé (depuis maintenant, il s’agit du seul fichier de ressources dans le projet). La directive x:Uid sur le TextBlock entraîne une recherche des identifiants de propriété dans Resources.resw qui contiennent l'identifiant de ressource de type chaîne « Greeting ». Les identifiants de propriété « Greeting.Text » et « Greeting.Width » sont trouvés et leurs valeurs sont appliquées au TextBlock, en remplaçant les valeurs définies localement dans la balise. La valeur « Greeting.Foreground » est également appliquée si vous l’avez ajouté. Mais seuls les identifiants de propriété sont utilisés pour définir des propriétés sur des éléments de balise XAML. Par conséquent, la définition de x:Uid sur « Farewell » sur ce TextBlock n’aurait aucun effet. Resources.reswcontient l’identificateur de ressource de chaîne « Farewell », mais il ne contient aucun identificateur de propriété pour celui-ci.

Lors de l’affectation d’un identifiant de ressource de chaîne à un élément XAML, assurez-vous que tous les identifiants de propriété de cet identificateur sont appropriés pour l’élément XAML. Par exemple, si vous définissez x:Uid="Greeting" sur un TextBlock, « Greeting.Text » est résolu, car le type TextBlock a une propriété Texte. Toutefois, si vous définissez x:Uid="Greeting" sur un Bouton, « Greeting.Text » provoque une erreur d’exécution, car le type Bouton n’a pas de propriété Texte. Une solution pour ce cas consiste à créer un identifiant de propriété nommé « ButtonGreeting.Content » et à définir x:Uid="ButtonGreeting" sur le bouton.

Au lieu de définir Width à partir d’un fichier de ressources, vous souhaiterez probablement autoriser les contrôles à dimensionner dynamiquement dans le contenu.

Remarque

Pour les propriétés jointes, vous avez besoin d’une syntaxe spéciale dans la colonne Nom d’un fichier .resw. Par exemple, pour définir une valeur pour la propriété jointe AutomationProperties.Name pour l’identifiant « Greeting », il s’agit de ce que vous saisissez dans la colonne Nom.

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Reportez-vous à un identifiant de ressource de chaîne à partir du code

Vous pouvez charger explicitement une ressource de chaîne en fonction d’un identifiant de ressource de chaîne simple.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Vous pouvez utiliser ce même code à partir d’un projet bibliothèque de classes. Au moment de l’exécution, les ressources de l’application qui héberge la bibliothèque sont chargées. Nous vous recommandons de charger des ressources à partir de l’application qui l’héberge, car l’application est susceptible d’avoir un plus grand degré de localisation. Si une bibliothèque doit fournir des ressources, elle doit donner à son application d’hébergement la possibilité de remplacer ces ressources en tant qu’entrée.

Si un nom de ressource est segmenté (il contient des caractères « . »), remplacez les points par des barres obliques (« / ») dans le nom de la ressource. Les identifiants de propriété, par exemple, contiennent des points ; vous devrez donc effectuer cette substitution pour charger l’un de ces éléments à partir du code.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

En cas de doute, vous pouvez utiliser MakePri.exe pour vider le fichier IRP de votre application. Chaque ressource uri est affichée dans le fichier vidé.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Reportez-vous à un identifiant de ressource de chaîne à partir du manifeste du package d’application

  1. Ouvrez le fichier source du manifeste du package d’application (le Package.appxmanifest fichier), dans lequel par défaut les fichiers de votre application Display name sont exprimés sous la forme d’un littéral de chaîne.

    Capture d’écran du fichier Package.appxmanifest montrant l’onglet Application avec le nom d’affichage défini sur Adventure Works Cycles.

  2. Pour rendre une version localisable de cette chaîne, ouvrez Resources.resw et ajoutez une nouvelle ressource de chaîne avec le nom « AppDisplayName » et la valeur « Adventure Works Cycles ».

  3. Remplacez le littéral de chaîne du nom complet par une référence à l’identifiant de ressource de chaîne que vous venez de créer (« AppDisplayName »). Pour ce faire, vous utilisez le schéma ms-resource URI (Uniform Resource Identifier).

    Capture d’écran du fichier Package.appxmanifest montrant l’onglet Application avec le nom d’affichage défini sur M S resource App Display Name.

  4. Répétez ce processus pour chaque chaîne de votre manifeste que vous souhaitez localiser. Par exemple, le nom court de votre application (que vous pouvez configurer pour apparaître sur la vignette de votre application au démarrage). Pour obtenir la liste de tous les éléments du manifeste du package d’application que vous pouvez localiser, consultez les éléments de manifeste localisables.

Localiser les ressources de chaîne

  1. Effectuez une copie de votre fichier de ressources (.resw) pour une autre langue.

    1. Sous « Chaînes », créez un sous-dossier et nommez-le « de-DE » pour Allemand (Allemagne).

    Remarque

    Pour le nom du dossier, vous pouvez utiliser n’importe quelle balise de langue BCP-47. Consultez Personnaliser vos ressources pour la langue, la mise à l’échelle et d’autres critéres pour plus d’informations sur le qualificateur de langue et une liste de balises de langue courantes. 2. Effectuez une copie de Strings/en-US/Resources.resw dans le dossier Strings/de-DE.

  2. Traduire les chaînes.

    1. Ouvrez Strings/de-DE/Resources.resw et traduisez les valeurs dans la colonne Valeur. Vous n’avez pas besoin de traduire les commentaires.

    Strings/de-DE/Resources.resw

    ajouter une ressource, allemand

Si vous le souhaitez, vous pouvez répéter les étapes 1 et 2 pour une autre langue.

Strings/fr-FR/Resources.resw

ajouter une ressource, français

Tester votre application

Testez l’application pour votre langue d’affichage par défaut. Vous pouvez ensuite modifier la langue d'affichage dans Paramètres>Heure et langue>Région et langue>Langues et retester votre application. Examinez les chaînes de votre IU et également dans l’interpréteur de commandes (par exemple, votre barre de titre, qui est votre nom complet) et le nom court de vos vignettes.

Remarque

Si un nom de dossier est trouvé qui correspond au paramètre de langue d’affichage, le fichier de ressources à l’intérieur de ce dossier est chargé. Dans le cas contraire, le secours se termine par les ressources de la langue par défaut de votre application.

Factoring des chaînes dans plusieurs fichiers de ressources

Vous pouvez conserver toutes vos chaînes dans un fichier de ressources unique (resw) ou les factoriser sur plusieurs fichiers de ressources. Par exemple, vous souhaiterez peut-être conserver vos messages d’erreur dans un fichier de ressources, vos chaînes de manifeste du package d’application dans une autre et vos chaînes d’IU dans un troisième. Il s’agit de ce que votre structure de dossiers ressemblerait dans ce cas.

Capture d’écran du panneau Solution montrant le dossier Adventure Works Cycles > Strings avec les dossiers et fichiers régionaux allemands, anglais et français.

Pour étendre une référence d’identifiant de ressource de chaîne à un fichier particulier, vous venez d’ajouter /<resources-file-name>/ avant l’identifiant. L’exemple de balise ci-dessous suppose que ErrorMessages.resw contient une ressource dont le nom est « PasswordTooWeak.Text » et dont la valeur décrit l’erreur.

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Vous devez uniquement ajouter /<resources-file-name>/ avant l’identificateur de ressource de chaîne pour les fichiers de ressources autres que Resources.resw. C’est parce que « Resources.resw » est le nom de fichier par défaut, c’est ce qui est supposé si vous omettez un nom de fichier (comme nous l’avons fait dans les exemples précédents de cette rubrique).

L’exemple de code ci-dessous part du principe que ErrorMessages.resw contient une ressource dont le nom est « MismatchedPasswords » et dont la valeur décrit l’erreur.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Si vous deviez déplacer votre ressource « AppDisplayName » hors de Resources.resw et vers ManifestResources.resw, dans le manifeste du package d’application, vous devez passer ms-resource:AppDisplayName à ms-resource:/ManifestResources/AppDisplayName.

Si un nom de fichier de ressource est segmenté (il contient des caractères « . »), laissez les points dans le nom lorsque vous le référencez. Ne remplacez pas les points par des caractères de barre oblique (« / ») comme vous le feriez pour un nom de ressource.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("Err.Msgs");

En cas de doute, vous pouvez utiliser MakePri.exe pour vider le fichier IRP de votre application. Chaque ressource uri est affichée dans le fichier vidé.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Charger une chaîne pour une langue spécifique ou un autre contexte

ResourceContext par défaut (obtenu lors de la création d’un ResourceLoader) contient une valeur de qualificateur pour chaque nom de qualificateur, représentant le contexte d’exécution par défaut (en d’autres termes, les paramètres de l’utilisateur et de l’ordinateur actuels). Les fichiers de ressources (.resw) sont mis en correspondance, en fonction des qualificateurs dans leurs noms, par rapport aux valeurs de qualificateur dans ce contexte d’exécution.

Toutefois, il peut arriver que votre application remplace les paramètres système et qu’elle soit explicite sur la langue, la mise à l’échelle ou une autre valeur de qualificateur à utiliser lorsque vous recherchez un fichier de ressources correspondant à charger. Par exemple, vous souhaiterez peut-être que vos utilisateurs puissent sélectionner une autre langue pour les info-bulles ou les messages d’erreur.

Vous pouvez le faire en construisant un nouveau ResourceContext, en remplaçant ses valeurs, puis en utilisant cet objet de contexte dans vos recherches de chaîne.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

L’utilisation de QualifierValues comme dans l’exemple de code ci-dessus fonctionne pour n’importe quel qualificateur. Pour le cas particulier de langue, vous pouvez également le faire à la place.

resourceContext.Languages = new string[] { "de-DE" };

Charger des chaînes à partir d’une bibliothèque de classes

Les ressources de chaîne d’une bibliothèque de classes référencées sont généralement ajoutées dans un sous-dossier du package dans lequel ils sont inclus pendant le processus de génération. L’identifiant de ressource d’une telle chaîne prend généralement la forme LibraryName/ResourcesFileName/ResourceIdentifier.

Une bibliothèque peut obtenir un ResourceLoader pour ses propres ressources. Par exemple, le code suivant illustre la façon dont une bibliothèque ou une application qui le référence peut obtenir un ResourceLoader pour les ressources de chaîne de la bibliothèque.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader("ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

En cas de doute sur le chemin d’accès, vous pouvez spécifier les options de ligne de commande MakePri.exe pour vider le fichier IRP de votre composant ou bibliothèque. Chaque ressource uri est affichée dans le fichier vidé.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Chargement de chaînes à partir d’autres packages

Les ressources d’un package de l’application sont gérées et accessibles via les propres ResourceMap de niveau supérieur du package accessibles à partir de ResourceManager. Dans chaque package, différents composants peuvent avoir leurs propres sous-arborescences ResourceMap, auxquelles vous pouvez accéder via ResourceMap.GetSubtree.

Un package d’infrastructure peut accéder à ses propres ressources avec un URI d’identifiant de ressource absolu. Consultez également les schémas d’URI dans la documentation UWP pour plus d’informations.

Chargement de chaînes dans des applications non empaquetées

À compter de Windows Version 1903 (mise à jour de mai 2019), les applications non empaquetées peuvent également tirer profit du système de gestion des ressources.

Créez simplement vos contrôles/bibliothèques SDK d'application Windows et stockez toutes les chaînes dans un fichier de ressources. Vous pouvez ensuite faire référence à un identifiant de ressource de chaîne à partir de XAML, faire référence à un identifiant de ressource de chaîne à partir du code ou charger des chaînes à partir d’une bibliothèque de classes.

Pour utiliser des ressources dans des applications non empaquetées, vous devez effectuer quelques opérations :

  1. Utilisez le constructeur surchargé de ResourceManager pour passer le nom de fichier du fichier .pri de votre application lors de la résolution des ressources à partir du code, car il n’existe aucune vue par défaut dans les scénarios non empaquetés.
  2. Utilisez MakePri.exe pour générer manuellement le fichier resources.pri de votre application.
    • Exécutez makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri
    • <PRICONFIG> doit omettre la section « <empaquetage> » afin que toutes les ressources soient regroupées dans un fichier resources.pri unique. Si vous utilisez le fichier de configuration MakePri.exe par défaut créé par createconfig, vous devez supprimer manuellement la section « <empaquetage> » après sa création.
    • <PRICONFIG> doit contenir tous les indexeurs pertinents requis pour fusionner toutes les ressources de votre projet dans un fichier resources.pri unique. Le fichier de configuration MakePri.exe par défaut créé par createconfig inclut tous les indexeurs.
    • Si vous n’utilisez pas la configuration par défaut, vérifiez que l’indexeur PRI est activé (passez en revue la configuration par défaut pour savoir comment procéder) pour fusionner les PRIs trouvées à partir de références de projet, de références NuGet, et ainsi de suite, qui se trouvent dans la racine du projet.

      Remarque

      En omettant /IndexName, et par le projet ne disposant pas d’un manifeste de l’application, l’espace de noms IndexName/racine du fichier IRP est automatiquement défini sur Application, que le runtime comprend pour les applications non empaquetées (cela supprime la dépendance matérielle précédente sur l’ID de package). Lorsque vous spécifiez des URI de ressources, les références ms-resource:/// qui omettent l'espace de noms racine déduisent Application comme espace de noms racine pour les applications non packagées (ou vous pouvez spécifier Application explicitement comme dans ms-resource://Application/).

  3. Copiez le fichier IRP dans l’annuaire de sortie de build du fichier .exe
  4. Exécuter le fichier .exe

    Remarque

    Le système de gestion des ressources utilise la langue d’affichage du système plutôt que la liste de langues par défaut de l’utilisateur lors de la résolution des ressources en fonction de la langue dans les applications non empaquetées. La liste de langues par défaut de l’utilisateur est utilisée uniquement pour les applications empaquetées du Kit de développement logiciel (SDK) d’application Windows.

Important

Vous devez régénérer manuellement les fichiers IRP chaque fois que les ressources sont modifiées. Nous vous recommandons d’utiliser un script post-build qui gère la commande MakePri.exe et copie la sortie resources.pri dans l’annuaire .exe.

API importantes

Voir aussi