Fournir des ressources localisées pour les langues et les cultures dans une application ASP.NET Core
Remarque
Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.
Avertissement
Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.
Important
Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.
Pour la version actuelle, consultez la version .NET 8 de cet article.
Par Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana et Hisham Bin Ateya
L’une des tâches relatives à la localisation d’une application consiste à fournir des chaînes localisées dans des fichiers de ressources. Cet article traite de l’utilisation des fichiers de ressources.
SupportedCultures et SupportedUICultures
ASP.NET Core a deux collections de valeurs de culture, SupportedCultures et SupportedUICultures. L’objet CultureInfo pour SupportedCultures détermine les résultats des fonctions qui dépendent de la culture, par exemple la mise en forme des dates, des heures, des nombres et des devises. SupportedCultures détermine également l’ordre de tri du texte, les conventions de casse et les comparaisons de chaînes. Pour plus d’informations sur la façon dont le serveur obtient la culture, consultez StringComparer.CurrentCulture. SupportedUICultures détermine quelles sont les chaînes traduites (provenant de fichiers .resx) qui sont recherchées par ResourceManager. ResourceManager recherche simplement les chaînes spécifiques à la culture, qui sont déterminées par CurrentUICulture. Chaque thread dans .NET a des objets CurrentCulture et CurrentUICulture. ASP.NET Core inspecte ces valeurs lors du rendu des fonctions qui dépendent de la culture. Par exemple, si la culture du thread actuel a la valeur « en-US » (anglais, États-Unis), DateTime.Now.ToLongDateString() affiche « Thursday, February 18, 2016 », mais si CurrentCulture a la valeur « es-ES » (espagnol, Espagne), la sortie est « jueves, 18 de febrero de 2016 ».
Fichiers de ressources
NOTE : ResX Viewer and Editor fournit un mécanisme alternatif pour travailler avec des fichiers de ressources à l'aide de Visual Studio Code.
Un fichier de ressources est un mécanisme utile pour séparer les chaînes localisables du code. Les chaînes traduites spécifiques aux autres langues que la langue par défaut sont isolées dans des fichiers de ressources .resx. Par exemple, vous pouvez être amené à créer un fichier de ressources en espagnol nommé Welcome.es.resx, qui contient des chaînes traduites. « es » correspond au code de langue pour l’espagnol. Pour créer ce fichier de ressources dans Visual Studio :
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier destiné à contenir le fichier de ressources, puis sélectionnez Ajouter>Nouvel élément.
Dans la zone Rechercher dans les modèles installés, entrez « ressource » et nommez le fichier.
Entrez la valeur de la clé (chaîne native) dans la colonne Nom et la chaîne traduite dans la colonne Valeur.
Visual Studio présente le fichier Welcome.es.resx.
Nommage du fichier de ressources
Les ressources sont nommées selon le nom de type complet de leur classe moins le nom de l’assembly. Par exemple, une ressource en français dans un projet dont l’assembly principal est LocalizationWebsite.Web.dll pour la classe LocalizationWebsite.Web.Startup serait nommée Startup.fr.resx. Une ressource pour la classe LocalizationWebsite.Web.Controllers.HomeController serait nommée Controllers.HomeController.fr.resx. Si l’espace de noms de votre classe ciblée n’est pas identique au nom de l’assembly, vous aurez besoin du nom de type complet. Par exemple, dans l’exemple de projet, une ressource pour le type ExtraNamespace.Tools serait nommée ExtraNamespace.Tools.fr.resx.
Dans l’exemple de projet, la méthode ConfigureServices définit le ResourcesPath sur « Resources ». Ainsi, le chemin d’accès relatif du projet pour le fichier de ressources en français du contrôleur home est Resources/Controllers.HomeController.fr.resx. Vous pouvez également utiliser des dossiers pour organiser les fichiers de ressources. Pour le contrôleur home, le chemin d’accès serait Resources/Controllers/HomeController.fr.resx. Si vous n’utilisez pas l’option ResourcesPath, le fichier .resx se trouve dans le répertoire de base du projet. Le fichier de ressources pour HomeController serait nommé Controllers.HomeController.fr.resx. Le choix de l’utilisation de la convention d’affectation de noms avec des points ou un chemin dépend de la façon dont vous souhaitez organiser vos fichiers de ressources.
| Nom de la ressource | Affectation de noms avec des points ou un chemin |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Points |
| Resources/Controllers/HomeController.fr.resx | Chemin d’accès |
Les fichiers de ressources qui utilisent @inject IViewLocalizer dans les vues Razor suivent un modèle similaire. Le fichier de ressources d’une vue peut être nommé selon la convention avec des points ou un chemin. Les fichiers de ressources d’une vue Razor imitent le chemin de son fichier de vue associé. Si nous affectons à ResourcesPath la valeur « Resources », le fichier de ressources en français associé à la vue Views/Home/About.cshtml peut porter l’un des noms suivants :
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
Si vous n’utilisez pas l’option ResourcesPath, le fichier .resx d’un affichage se trouve dans le même dossier que l’affichage.
RootNamespaceAttribute
L’attribut RootNamespaceAttribute fournit l’espace de noms racine d’un assembly quand il est différent du nom de l’assembly.
Avertissement
Cela peut se produire quand le nom d’un projet n’est pas un identificateur .NET valide. Par exemple, my-project-name.csproj utilise l’espace de noms racine my_project_name et le nom d’assembly my-project-name, ce qui entraîne cette erreur.
Si l’espace de noms racine d’un assembly est différent du nom de l’assembly :
- La localisation ne fonctionne pas par défaut.
- La localisation échoue en raison du mode de recherche des ressources dans l’assembly.
RootNamespaceest une valeur de build qui n’est pas accessible au processus exécutant.
Si RootNamespace est différent de AssemblyName, incluez ce qui suit dans AssemblyInfo.cs (en remplaçant les valeurs de paramètre par les valeurs réelles) :
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Le code précédent permet de résoudre correctement les fichiers resx.
Comportement de secours pour la culture
Lors de la recherche d’une ressource, la localisation met en œuvre une « alternative de secours pour la culture ». Elle commence par la culture demandée : si elle est introuvable, il revient à la culture parente de cette culture. Notez que la propriété CultureInfo.Parent représente la culture parente. Cela signifie généralement (mais pas toujours) la suppression de l’indicateur national du code de langue et de culture. Par exemple, le dialecte de l’espagnol parlé au Mexique est « es-MX ». Le parent est « es » (espagnol), qui n’est spécifique à aucun pays.
Imaginez que votre site reçoive une demande pour une ressource « Bienvenue » avec la culture « fr-CA ». Le système de localisation recherche les ressources suivantes, dans l’ordre, et sélectionne la première correspondance :
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (si
NeutralResourcesLanguageest « fr-CA »)
Par exemple, si vous supprimez l’indicateur de culture « .fr » alors que la culture définie est le français, le fichier de ressources par défaut est lu et les chaînes sont localisées. Le gestionnaire de ressources désigne une ressource par défaut ou de secours pour les cas où rien ne correspond à la culture demandée. Si vous voulez simplement retourner la clé quand une ressource est manquante pour la culture demandée, vous ne devez pas avoir de fichier de ressources par défaut.
Générer des fichiers de ressources avec Visual Studio
Si vous créez un fichier de ressources dans Visual Studio sans culture dans le nom de fichier (par exemple, Welcome.resx), Visual Studio crée une classe C# avec une propriété pour chaque chaîne. Ce n’est généralement pas ce que vous souhaitez avec ASP.NET Core. Vous n’avez habituellement pas de fichier de ressources .resx par défaut (un fichier .resx sans nom de culture). Nous vous suggérons donc de créer le fichier .resx avec un nom de culture (par exemple, Welcome.fr.resx). Lorsque vous créez un fichier .resx avec un nom de culture, Visual Studio ne génère pas le fichier de classe.
Ajouter d’autres cultures
Chaque combinaison de langue et de culture (autres que la langue par défaut) nécessite un fichier de ressources unique. Si vous souhaitez créer des fichiers de ressources pour différentes cultures et différents paramètres régionaux, vous devez créer des fichiers de ressources dans lesquels les codes de langue font partie du nom de fichier (par exemple en-us, fr-ca et en-gb). Ces codes sont placés entre le nom de fichier et l’extension de fichier .resx, comme dans Welcome.es-MX.resx (Espagnol/Mexique).
Étapes suivantes
La localisation d’une application implique également les tâches suivantes :
- Rendre le contenu de l’application localisable.
- Implémenter une stratégie de sélection de la langue/culture pour chaque requête
Ressources supplémentaires
- Fournisseur de culture d’URL qui utilise des intergiciels comme filtres dans ASP.NET Core
- Application globale de RouteDataRequest CultureProvider avec des intergiciel en tant que filtres
- Globalisation et localisation dans ASP.NET Core
- Rendre le contenu d’une application ASP.NET Core localisable
- Stratégies de sélection de la langue et de la culture dans une application ASP.NET Core localisée
- Résoudre les problèmes liés à la localisation ASP.NET Core
- Internationalisation et localisation d’applications .NET
- Projet Localization.StarterWeb utilisé dans l’article.
- Ressources dans les fichiers .resx
- Kit de ressources pour application multilingue Microsoft
- Localisation et classes génériques
Par Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana et Hisham Bin Ateya
L’une des tâches relatives à la localisation d’une application consiste à fournir des chaînes localisées dans des fichiers de ressources. Cet article traite de l’utilisation des fichiers de ressources.
SupportedCultures et SupportedUICultures
ASP.NET Core a deux collections de valeurs de culture, SupportedCultures et SupportedUICultures. L’objet CultureInfo pour SupportedCultures détermine les résultats des fonctions qui dépendent de la culture, par exemple la mise en forme des dates, des heures, des nombres et des devises. SupportedCultures détermine également l’ordre de tri du texte, les conventions de casse et les comparaisons de chaînes. Pour plus d’informations sur la façon dont le serveur obtient la culture, consultez StringComparer.CurrentCulture. SupportedUICultures détermine quelles sont les chaînes traduites (provenant de fichiers .resx) qui sont recherchées par ResourceManager. ResourceManager recherche simplement les chaînes spécifiques à la culture, qui sont déterminées par CurrentUICulture. Chaque thread dans .NET a des objets CurrentCulture et CurrentUICulture. ASP.NET Core inspecte ces valeurs lors du rendu des fonctions qui dépendent de la culture. Par exemple, si la culture du thread actuel a la valeur « en-US » (anglais, États-Unis), DateTime.Now.ToLongDateString() affiche « Thursday, February 18, 2016 », mais si CurrentCulture a la valeur « es-ES » (espagnol, Espagne), la sortie est « jueves, 18 de febrero de 2016 ».
Fichiers de ressources
Un fichier de ressources est un mécanisme utile pour séparer les chaînes localisables du code. Les chaînes traduites spécifiques aux autres langues que la langue par défaut sont isolées dans des fichiers de ressources .resx. Par exemple, vous pouvez être amené à créer un fichier de ressources en espagnol nommé Welcome.es.resx, qui contient des chaînes traduites. « es » correspond au code de langue pour l’espagnol. Pour créer ce fichier de ressources dans Visual Studio :
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier destiné à contenir le fichier de ressources, puis sélectionnez Ajouter>Nouvel élément.
Dans la zone Rechercher dans les modèles installés, entrez « ressource » et nommez le fichier.
Entrez la valeur de la clé (chaîne native) dans la colonne Nom et la chaîne traduite dans la colonne Valeur.
Visual Studio présente le fichier Welcome.es.resx.
Nommage du fichier de ressources
Les ressources sont nommées selon le nom de type complet de leur classe moins le nom de l’assembly. Par exemple, une ressource en français dans un projet dont l’assembly principal est LocalizationWebsite.Web.dll pour la classe LocalizationWebsite.Web.Startup serait nommée Startup.fr.resx. Une ressource pour la classe LocalizationWebsite.Web.Controllers.HomeController serait nommée Controllers.HomeController.fr.resx. Si l’espace de noms de votre classe ciblée n’est pas identique au nom de l’assembly, vous aurez besoin du nom de type complet. Par exemple, dans l’exemple de projet, une ressource pour le type ExtraNamespace.Tools serait nommée ExtraNamespace.Tools.fr.resx.
Dans l’exemple de projet, la méthode ConfigureServices définit le ResourcesPath sur « Resources ». Ainsi, le chemin d’accès relatif du projet pour le fichier de ressources en français du contrôleur home est Resources/Controllers.HomeController.fr.resx. Vous pouvez également utiliser des dossiers pour organiser les fichiers de ressources. Pour le contrôleur home, le chemin d’accès serait Resources/Controllers/HomeController.fr.resx. Si vous n’utilisez pas l’option ResourcesPath, le fichier .resx se trouve dans le répertoire de base du projet. Le fichier de ressources pour HomeController serait nommé Controllers.HomeController.fr.resx. Le choix de l’utilisation de la convention d’affectation de noms avec des points ou un chemin dépend de la façon dont vous souhaitez organiser vos fichiers de ressources.
| Nom de la ressource | Affectation de noms avec des points ou un chemin |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Points |
| Resources/Controllers/HomeController.fr.resx | Chemin d’accès |
Les fichiers de ressources qui utilisent @inject IViewLocalizer dans les vues Razor suivent un modèle similaire. Le fichier de ressources d’une vue peut être nommé selon la convention avec des points ou un chemin. Les fichiers de ressources d’une vue Razor imitent le chemin de son fichier de vue associé. Si nous affectons à ResourcesPath la valeur « Resources », le fichier de ressources en français associé à la vue Views/Home/About.cshtml peut porter l’un des noms suivants :
Resources/Views/Home/About.fr.resx
Resources/Views.Home.About.fr.resx
Si vous n’utilisez pas l’option ResourcesPath, le fichier .resx d’un affichage se trouve dans le même dossier que l’affichage.
RootNamespaceAttribute
L’attribut RootNamespaceAttribute fournit l’espace de noms racine d’un assembly quand il est différent du nom de l’assembly.
Avertissement
Cela peut se produire quand le nom d’un projet n’est pas un identificateur .NET valide. Par exemple, my-project-name.csproj utilise l’espace de noms racine my_project_name et le nom d’assembly my-project-name, ce qui entraîne cette erreur.
Si l’espace de noms racine d’un assembly est différent du nom de l’assembly :
- La localisation ne fonctionne pas par défaut.
- La localisation échoue en raison du mode de recherche des ressources dans l’assembly.
RootNamespaceest une valeur de build qui n’est pas accessible au processus exécutant.
Si RootNamespace est différent de AssemblyName, incluez ce qui suit dans AssemblyInfo.cs (en remplaçant les valeurs de paramètre par les valeurs réelles) :
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Le code précédent permet de résoudre correctement les fichiers resx.
Comportement de secours pour la culture
Lors de la recherche d’une ressource, la localisation met en œuvre une « alternative de secours pour la culture ». Elle commence par la culture demandée : si elle est introuvable, il revient à la culture parente de cette culture. Notez que la propriété CultureInfo.Parent représente la culture parente. Cela signifie généralement (mais pas toujours) la suppression de l’indicateur national du code de langue et de culture. Par exemple, le dialecte de l’espagnol parlé au Mexique est « es-MX ». Le parent est « es » (espagnol), qui n’est spécifique à aucun pays.
Imaginez que votre site reçoive une demande pour une ressource « Bienvenue » avec la culture « fr-CA ». Le système de localisation recherche les ressources suivantes, dans l’ordre, et sélectionne la première correspondance :
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (si
NeutralResourcesLanguageest « fr-CA »)
Par exemple, si vous supprimez l’indicateur de culture « .fr » alors que la culture définie est le français, le fichier de ressources par défaut est lu et les chaînes sont localisées. Le gestionnaire de ressources désigne une ressource par défaut ou de secours pour les cas où rien ne correspond à la culture demandée. Si vous voulez simplement retourner la clé quand une ressource est manquante pour la culture demandée, vous ne devez pas avoir de fichier de ressources par défaut.
Générer des fichiers de ressources avec Visual Studio
Si vous créez un fichier de ressources dans Visual Studio sans culture dans le nom de fichier (par exemple, Welcome.resx), Visual Studio crée une classe C# avec une propriété pour chaque chaîne. Ce n’est généralement pas ce que vous souhaitez avec ASP.NET Core. Vous n’avez habituellement pas de fichier de ressources .resx par défaut (un fichier .resx sans nom de culture). Nous vous suggérons donc de créer le fichier .resx avec un nom de culture (par exemple, Welcome.fr.resx). Lorsque vous créez un fichier .resx avec un nom de culture, Visual Studio ne génère pas le fichier de classe.
Ajouter d’autres cultures
Chaque combinaison de langue et de culture (autres que la langue par défaut) nécessite un fichier de ressources unique. Si vous souhaitez créer des fichiers de ressources pour différentes cultures et différents paramètres régionaux, vous devez créer des fichiers de ressources dans lesquels les codes de langue font partie du nom de fichier (par exemple en-us, fr-ca et en-gb). Ces codes sont placés entre le nom de fichier et l’extension de fichier .resx, comme dans Welcome.es-MX.resx (Espagnol/Mexique).
Étapes suivantes
La localisation d’une application implique également les tâches suivantes :
- Rendre le contenu de l’application localisable.
- Implémenter une stratégie de sélection de la langue/culture pour chaque requête
Ressources supplémentaires
- Globalisation et localisation dans ASP.NET Core
- Rendre le contenu d’une application ASP.NET Core localisable
- Stratégies de sélection de la langue et de la culture dans une application ASP.NET Core localisée
- Résoudre les problèmes liés à la localisation ASP.NET Core
- Internationalisation et localisation d’applications .NET
- Projet Localization.StarterWeb utilisé dans l’article.
- Ressources dans les fichiers .resx
- Kit de ressources pour application multilingue Microsoft
- Localisation et classes génériques
