Partager via

Xamarin.Forms Localisation de chaîne et d’image

  • Article

La localisation est le processus d’adaptation d’une application pour répondre aux exigences linguistiques ou culturelles spécifiques d’un marché cible. Pour effectuer la localisation, le texte et les images d’une application peuvent avoir besoin d’être traduits en plusieurs langues. Une application localisée affiche automatiquement le texte traduit en fonction des paramètres de culture de l’appareil mobile :

Captures d’écran de l’application de localisation sur iOS et Android

Le .NET Framework inclut un mécanisme intégré pour localiser des applications à l’aide de fichiers de ressources Resx. Un fichier de ressources stocke du texte et d’autres contenus sous forme de paires nom/valeur qui permettent à l’application de récupérer du contenu pour une clé fournie. Les fichiers de ressources permettent de séparer le contenu localisé du code d’application.

L’utilisation de fichiers de ressources pour localiser Xamarin.Forms des applications nécessite que vous procédiez comme suit :

  1. Créez des fichiers Resx contenant du texte traduit.
  2. Spécifiez la culture par défaut dans le projet partagé.
  3. Localiser le texte en Xamarin.Forms.
  4. Localisez les images en fonction des paramètres de culture pour chaque plateforme.
  5. Localisez le nom de l’application sur chaque plateforme.
  6. Testez la localisation sur chaque plateforme.

Créer des fichiers Resx

Les fichiers de ressources sont des fichiers XML avec une extension .resx compilée en fichiers de ressources binaires (.resources) pendant le processus de génération. Visual Studio 2019 génère une classe qui fournit une API utilisée pour récupérer des ressources. Une application localisée contient généralement un fichier de ressources par défaut avec toutes les chaînes utilisées dans l’application, ainsi que des fichiers de ressources pour chaque langue prise en charge. L’exemple d’application possède un dossier Resx dans le projet partagé qui contient les fichiers de ressources et son fichier de ressources par défaut appelé AppResources.resx.

Les fichiers de ressources contiennent les informations suivantes pour chaque élément :

  • Le nom spécifie la clé utilisée pour accéder au texte dans le code.
  • La valeur spécifie le texte traduit.
  • Le commentaire est un champ facultatif contenant des informations supplémentaires.

Un fichier de ressources est ajouté avec la boîte de dialogue Ajouter un nouvel élément dans Visual Studio 2019 :

Ajouter une nouvelle ressource dans Visual Studio 2019

Une fois le fichier ajouté, les lignes peuvent être ajoutées pour chaque ressource texte :

Spécifier les ressources de texte par défaut dans un fichier .resx

Le paramètre déroulant Modificateur d’accès détermine la façon dont Visual Studio génère la classe utilisée pour accéder aux ressources. La définition du modificateur d’accès en résultats publics ou internes dans une classe générée avec le niveau d’accessibilité spécifié. La définition du modificateur d’accès sur Aucune génération de code ne génère pas de fichier de classe. Le fichier de ressources par défaut doit être configuré pour générer un fichier de classe, ce qui entraîne l’ajout d’un fichier avec l’extension .designer.cs ajoutée au projet.

Une fois le fichier de ressources par défaut créé, des fichiers supplémentaires peuvent être créés pour chaque culture prise en charge par l’application. Chaque fichier de ressources supplémentaire doit inclure la culture de traduction dans le nom de fichier et avoir le modificateur Access défini sur Aucune génération de code.

Au moment de l’exécution, l’application tente de résoudre une demande de ressource dans l’ordre de spécificité. Par exemple, si la culture de l’appareil est en-US , l’application recherche des fichiers de ressources dans cet ordre :

  1. AppResources.en-US.resx
  2. AppResources.en.resx
  3. AppResources.resx (par défaut)

La capture d’écran suivante montre un fichier de traduction espagnol nommé AppResources.es.resx :

Spécifier les ressources texte espagnoles par défaut dans un fichier .resx

Le fichier de traduction utilise les mêmes valeurs name spécifiées dans le fichier par défaut, mais contient des chaînes de langue espagnole dans la colonne Valeur . En outre, le modificateur d’accès est défini sur Aucune génération de code.

Un fichier de ressources est ajouté avec la boîte de dialogue Ajouter un nouveau fichier dans Visual Studio 2019 pour Mac :

Ajouter une nouvelle ressource dans Visual Studio 2019 pour Mac

Une fois qu’un fichier de ressources par défaut a été créé, le texte peut être ajouté en créant data des éléments dans l’élément root du fichier de ressources :

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="AddButton" xml:space="preserve">
        <value>Add Note</value>
    </data>
    <data name="NotesLabel" xml:space="preserve">
        <value>Notes:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>e.g. Get Milk</value>
    </data>
</root>

Vous pouvez créer un fichier de classe .designer.cs en définissant une propriété Outil personnalisé dans les options de fichier de ressources :

Outil personnalisé spécifié dans les propriétés d’un fichier de ressources

La définition de l’outil personnalisé sur PublicResXFileCodeGenerator entraîne la génération d’une classe avec public accès. La définition de l’outil personnalisé sur InternalResXFileCodeGenerator entraîne une classe générée avec internal accès. Une valeur d’outil personnalisé vide ne génère pas de classe. Le nom de classe généré correspond au nom du fichier de ressource. Par exemple, le fichier AppResources.resx entraîne la création d’une AppResources classe dans un fichier appelé AppResources.designer.cs.

Des fichiers de ressources supplémentaires peuvent être créés pour chaque culture prise en charge. Chaque fichier de langue doit inclure la culture de traduction dans le nom de fichier afin qu’un fichier ciblant es-MX soit nommé AppResources.es-MX.resx.

Au moment de l’exécution, l’application tente de résoudre une demande de ressource dans l’ordre de spécificité. Par exemple, si la culture de l’appareil est en-US , l’application recherche des fichiers de ressources dans cet ordre :

  1. AppResources.en-US.resx
  2. AppResources.en.resx
  3. AppResources.resx (par défaut)

Les fichiers de traduction de langue doivent avoir les mêmes valeurs de nom spécifiées que le fichier par défaut. Le code XML suivant montre le fichier de traduction espagnol nommé AppResources.es.resx :

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="NotesLabel" xml:space="preserve">
        <value>Notas:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>por ejemplo . comprar leche</value>
    </data>
    <data name="AddButton" xml:space="preserve">
        <value>Agregar nuevo elemento</value>
    </data>
</root>

Spécifier la culture par défaut

Pour que les fichiers de ressources fonctionnent correctement, l’application doit avoir un NeutralResourcesLanguage attribut spécifié. Dans le projet contenant les fichiers de ressources, le fichier AssemblyInfo.cs doit être personnalisé pour spécifier la culture par défaut. Le code suivant montre comment définir la NeutralResourcesLanguagevaleur en-US dans le fichier AssemblyInfo.cs :

using System.Resources;

// The resources from the neutral language .resx file are stored directly
// within the library assembly. For that reason, changing en-US to a different
// language in this line will not by itself change the language shown in the
// app. See the discussion of UltimateResourceFallbackLocation in the
// documentation for additional information:
// https://learn.microsoft.com/dotnet/api/system.resources.neutralresourceslanguageattribute
[assembly: NeutralResourcesLanguage("en-US")]

Avertissement

Si vous ne spécifiez pas l’attribut NeutralResourcesLanguage , la ResourceManager classe retourne null des valeurs pour toutes les cultures sans fichier de ressources spécifique. Lorsque la culture par défaut est spécifiée, les ResourceManager résultats retournés par le fichier Resx par défaut pour les cultures non prises en charge. Par conséquent, il est recommandé de toujours spécifier le texte afin que le NeutralResourcesLanguage texte soit affiché pour les cultures non prises en charge.

Une fois qu’un fichier de ressources par défaut a été créé et que la culture par défaut spécifiée dans le fichier AssemblyInfo.cs , l’application peut récupérer des chaînes localisées au moment de l’exécution.

Pour plus d’informations sur les fichiers de ressources, consultez Créer des fichiers de ressources pour les applications .NET.

Spécifier les langues prises en charge sur iOS

Sur iOS, vous devez déclarer toutes les langues prises en charge dans le fichier Info.plist de votre projet. Dans le fichier Info.plist , utilisez la vue Source pour définir un tableau pour la CFBundleLocalizations clé et fournissez des valeurs qui correspondent aux fichiers Resx. En outre, veillez à définir une langue attendue via la CFBundleDevelopmentRegion clé :

Capture d’écran de l’éditeur Info.plist montrant la section Localisations

Vous pouvez également ouvrir le fichier Info.plist dans un éditeur XML et ajouter les éléments suivants :

<key>CFBundleLocalizations</key>
<array>
    <string>de</string>
    <string>es</string>
    <string>fr</string>
    <string>ja</string>
    <string>pt</string> <!-- Brazil -->
    <string>pt-PT</string> <!-- Portugal -->
    <string>ru</string>
    <string>zh-Hans</string>
    <string>zh-Hant</string>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>

Remarque

Apple traite les portugais légèrement différemment que vous pourriez vous attendre. Pour plus d’informations, consultez Ajout de langues sur developer.apple.com.

Pour plus d’informations, consultez Spécification des langues par défaut et prises en charge dans Info.plist.

Spécifier les langues prises en charge sur UWP

Cela n’est nécessaire que si vous générez un bundle d’applications lorsque vous empaquetez l’application pour le chargement indépendant ou le store. Lorsque vous générez un bundle d’applications UWP, lorsque le bundle est installé, il charge uniquement les ressources associées aux paramètres de langue de l’appareil d’installation. Par conséquent, si l’appareil possède uniquement l’anglais, seules les ressources anglaises sont installées avec l’application. Pour plus d’informations et d’instructions, consultez les applications du Windows 8.1 Store : vérifiez que les ressources sont installées sur un appareil, qu’elles soient requises ou non.

Localiser du texte dans Xamarin.Forms

Le texte est localisé à Xamarin.Forms l’aide de la classe générée AppResources . Cette classe est nommée en fonction du nom de fichier de ressource par défaut. Étant donné que l’exemple de fichier de ressource de projet est nommé AppResources.resx, Visual Studio génère une classe correspondante appelée AppResources. Les propriétés statiques sont générées dans la AppResources classe pour chaque ligne du fichier de ressources. Les propriétés statiques suivantes sont générées dans la classe de l’exemple d’application AppResources :

  • AddButton
  • NotesLabel
  • NotesPlaceholder

L’accès à ces valeurs en tant que propriétés x :Static permet d’afficher du texte localisé en XAML :

<ContentPage ...
             xmlns:resources="clr-namespace:LocalizationDemo.Resx">
    <Label Text="{x:Static resources:AppResources.NotesLabel}" />
    <Entry Placeholder="{x:Static resources:AppResources.NotesPlaceholder}" />
    <Button Text="{x:Static resources:AppResources.AddButton}" />
</ContentPage>

Le texte localisé peut également être récupéré dans le code :

public LocalizedCodePage()
{
    Label notesLabel = new Label
    {
        Text = AppResources.NotesLabel,
        // ...
    };

    Entry notesEntry = new Entry
    {
        Placeholder = AppResources.NotesPlaceholder,
        //...
    };

    Button addButton = new Button
    {
        Text = AppResources.AddButton,
        // ...
    };

    Content = new StackLayout
    {
        Children = {
            notesLabel,
            notesEntry,
            addButton
        }
    };
}

Les propriétés de la AppResources classe utilisent la valeur actuelle du System.Globalization.CultureInfo.CurrentUICulture fichier de ressources de culture à partir duquel récupérer des valeurs.

Localiser des images

Outre le stockage du texte, les fichiers Resx sont capables de stocker plus que du texte, ils peuvent également stocker des images et des données binaires. Toutefois, les appareils mobiles ont une gamme de tailles d’écran et de densités, et chaque plateforme mobile dispose de fonctionnalités permettant d’afficher des images dépendantes de la densité. Par conséquent, la fonctionnalité de localisation d’images de plateforme doit être utilisée au lieu de stocker des images dans des fichiers de ressources.

Localiser des images sur Android

Sur Android, les dessinables localisés (images) sont stockés à l’aide d’une convention d’affectation de noms pour les dossiers du répertoire Ressources . Les dossiers sont nommés dessinables avec un suffixe pour la langue cible. Par exemple, le dossier espagnol est nommé drawable-es.

Lorsqu’un code de paramètres régionaux à quatre lettres est requis, Android nécessite un r supplémentaire suivant le tiret. Par exemple, le dossier des paramètres régionaux du Mexique (es-MX) doit être nommé drawable-es-rMX. Les noms de fichiers image dans chaque dossier de paramètres régionaux doivent être identiques :

Images localisées dans le projet Android

Pour plus d’informations, consultez Localisation Android.

Localiser des images sur iOS

Sur iOS, les images localisées sont stockées à l’aide d’une convention d’affectation de noms pour les dossiers du répertoire Ressources . Le dossier par défaut est nommé Base.lproj. Les dossiers spécifiques à la langue sont nommés avec le nom de la langue ou des paramètres régionaux, suivis de .lproj. Par exemple, le dossier espagnol est nommé es.lproj.

Les codes locaux à quatre lettres fonctionnent comme des codes de langue à deux lettres. Par exemple, le dossier des paramètres régionaux du Mexique (es-MX) doit être nommé es-MX.lproj. Les noms de fichiers image dans chaque dossier de paramètres régionaux doivent être identiques :

Images localisées dans le projet iOS

Remarque

iOS prend en charge la création d’un catalogue de ressources localisé au lieu d’utiliser la structure de dossiers .lproj. Toutefois, ceux-ci doivent être créés et gérés dans Xcode.

Pour plus d’informations, consultez localisation iOS.

Localiser des images sur UWP

Sur UWP, les images localisées sont stockées à l’aide d’une convention d’affectation de noms pour les dossiers du répertoire Assets/Images . Les dossiers sont nommés avec la langue ou les paramètres régionaux. Par exemple, le dossier de langue espagnole est nommé es et le dossier des paramètres régionaux du Mexique doit être nommé es-MX. Les noms de fichiers image dans chaque dossier de paramètres régionaux doivent être identiques :

Images localisées dans le projet UWP

Pour plus d’informations, consultez Localisation UWP.

Consommer des images localisées

Étant donné que chaque plateforme stocke des images avec une structure de fichiers unique, le code XAML utilise la OnPlatform classe pour définir la ImageSource propriété en fonction de la plateforme actuelle :

<Image>
    <Image.Source>
        <OnPlatform x:TypeArguments="ImageSource">
            <On Platform="iOS, Android" Value="flag.png" />
            <On Platform="UWP" Value="Assets/Images/flag.png" />
        </OnPlatform>
    </Image.Source>
</Image>

Remarque

L’extension OnPlatform de balisage offre un moyen plus concis de spécifier des valeurs spécifiques à la plateforme. Pour plus d’informations, consultez l’extension de balisage OnPlatform.

La source d’image peut être définie en fonction de la propriété dans le Device.RuntimePlatform code :

string imgSrc = Device.RuntimePlatform == Device.UWP ? "Assets/Images/flag.png" : "flag.png";
Image flag = new Image
{
    Source = ImageSource.FromFile(imgSrc),
    WidthRequest = 100
};

Localiser le nom de l’application

Le nom de l’application est spécifié par plateforme et n’utilise pas les fichiers de ressources Resx. Pour localiser le nom de l’application sur Android, consultez Localiser le nom de l’application sur Android. Pour localiser le nom de l’application sur iOS, consultez Localiser le nom de l’application sur iOS. Pour localiser le nom de l’application sur UWP, consultez Localiser les chaînes dans le manifeste du package UWP.

Localisation des tests

Le test de localisation est le mieux effectué en modifiant la langue de votre appareil. Il est possible de définir la valeur du System.Globalization.CultureInfo.CurrentUICulture code, mais le comportement est incohérent entre les plateformes, de sorte que cela n’est pas recommandé pour les tests.

Sur iOS, dans l’application paramètres, vous pouvez définir la langue de chaque application spécifiquement sans modifier la langue de votre appareil.

Sur Android, les paramètres de langue sont détectés et mis en cache au démarrage de l’application. Si vous modifiez des langues, vous devrez peut-être quitter et redémarrer l’application pour voir les modifications appliquées.