Vue d'ensemble des ressources des pages Web ASP.NET

Article
10/22/2014

Mise à jour : novembre 2007

Si vous créez des pages Web qui seront lues par les lecteurs de différentes langues, vous devez offrir aux lecteurs un moyen de consulter la page dans leur propre langue. Une approche possible est de recréer la page dans chaque langue. Toutefois, cette approche peut nécessiter beaucoup de travail, être sujette aux erreurs et être difficile à conserver lorsque vous modifiez la page d'origine.

ASP.NET vous permet de créer une page qui peut obtenir du contenu et d'autres données basées sur le paramètre de langue par défaut pour le navigateur ou sur le choix explicite de l'utilisateur d'une langue. Le contenu et d'autres données sont appelées ressources et de telles données peuvent être stockées dans des fichiers de ressources ou dans d'autres sources

Dans la page Web ASP.NET, vous configurez des contrôles pour obtenir leurs valeurs de propriété à partir de ressources. Au moment de l'exécution, les expressions de ressource sont remplacées par des ressources du fichier de ressources approprié.

Fichiers de ressources

Un fichier de ressources est un fichier XML qui contient les chaînes que vous souhaitez traduire dans des langues différentes ou chemins d'accès à des images. Le fichier de ressources contient des paires clé/valeur. Chaque paire est une ressource individuelle. Les noms de clés ne respectent pas la casse. Par exemple, un fichier de ressources peut contenir une ressource comprenant la clé Button1 et la valeur Submit.

Vous créez un fichier de ressources séparé pour chaque langue (par exemple, anglais et français) ou pour une langue et une culture (par exemple anglais du Royaume-Uni, anglais des États-Unis). Chaque fichier de ressources localisé a les mêmes paires clé/valeur ; la seule différence est qu'un fichier de ressources localisé peut contenir moins de ressources que le fichier de ressources par défaut. Le processus de secours de langue intégrée gère ensuite le chargement de la ressource neutre ou par défaut.

Les fichiers de ressources dans ASP.NET ont une extension .resx. Au moment de l'exécution, le fichier .resx est compilé dans un assembly qui est quelquefois appelé assembly satellite. Étant donné que les fichiers .resx sont compilés dynamiquement, de la même manière que les pages Web ASP.NET, vous ne devez pas créer les assemblys de ressource. La compilation réduit plusieurs fichiers de ressources de langue semblable dans le même assembly.

Lorsque vous créez des fichiers de ressources, commencez par créer un fichier .resx de base. Pour chaque langue que vous souhaitez prendre en charge, créez un nouveau fichier qui porte le même nom de fichier. Mais incluez au nom de fichier la langue ou la langue et la culture (nom de culture). Pour obtenir la liste des noms de cultures, consultez la classe CultureInfo. Par exemple, vous pouvez créer les éléments suivants :

WebResources.resx

Fichier de ressources de base. Il s'agit du fichier de ressources par défaut (fichier de secours).
WebResources.es.resx

Un fichier de ressources pour l'Espagnol.
WebResources.es-mx.resx

Fichier de ressources spécifique à l'espagnol (Mexique).
WebResources.de.resx

Un fichier de ressources pour l'Allemand.

Au moment de l'exécution, ASP.NET utilise le fichier de ressources qui est correspond le mieux au paramètre de la propriété CurrentUICulture. La culture d'interface utilisateur pour le thread est définie selon la culture d'interface utilisateur de la page. Par exemple, si la culture d'interface utilisateur actuelle est espagnole, ASP.NET utilise la version compilée du fichier WebResources.es.resx. S'il n'existe aucune concordance pour la culture d'interface utilisateur actuelle, ASP.NET utilise une culture de ressource de secours. Il démarre en recherchant les ressources d'une culture précise. Si ces ressources ne sont pas disponibles, il recherche les ressources d'une culture neutre. Enfin, si ces ressources sont introuvables, ASP.NET charge le fichier de ressources par défaut. Dans cet exemple, le fichier de ressources par défaut est WebResource.resx.

Création de fichiers de ressources pour les sites Web ASP.NET

Dans ASP.NET, vous pouvez créer des fichiers de ressources de portée différente. Vous pouvez créer des fichiers de ressources globales, ce qui signifie que vous pouvez lire le fichier de ressources à partir de toute page ou code qui se trouve dans le site Web. Vous pouvez également créer des fichiers de ressources locales qui stockent des ressources pour une page Web ASP.NET seule (fichier .aspx).

Fichiers de ressources globales

Vous créez un fichier de ressources globales en le plaçant dans le dossier réservé App_GlobalResources à la racine de l'application. Tout fichier .resx qui se trouve dans le dossier App_GlobalResources a une portée globale. En outre, ASP.NET génère un objet fortement typé qui vous offre une manière simple d'accéder par programme aux ressources globales.

Fichiers de ressources locales

Un fichier de ressources locales est un fichier qui s'applique à une seule page ou contrôle utilisateur ASP.NET (fichier ASP.NET qui possède l'extension de nom de fichier .aspx, .ascx, ou .master). Vous placez des fichiers de ressources locales dans des dossiers dont le nom réservé est App_LocalResources. Les dossiers App_LocalResources peuvent se trouver dans tout dossier de l'application, contrairement au dossier racine App_GlobalResources. Vous devez associer un jeu de fichiers de ressources à une page Web spécifique à l'aide du nom du fichier de ressources.

Par exemple, si vous avez une page nommée Default.aspx dans le dossier App_LocalResources, vous pouvez créer les fichiers suivants :

Default.aspx.resx Il s'agit du fichier de ressources locales par défaut (le fichier de ressources de secours) lorsqu'aucune correspondance de langue n'est trouvée.
Default.aspx.es.resx Il s'agit du fichier de ressources pour l'espagnol, qui ne contient pas d'informations de culture.
Default.aspx.es-mx.resx Il s'agit du fichier de ressources spécifique à l'espagnol (Mexique).
Default.aspx.fr.resx Il s'agit du fichier de ressources pour le français, qui ne contient pas d'informations de culture.

Le nom de base du fichier correspond au nom de fichier d'échange, suivi par une langue et un nom de culture et se termine avec l'extension .resx. Pour obtenir la liste des noms de cultures, consultez CultureInfo.

Localisation de ressources de script client

La prise en charge de la localisation du script client ASP.NET AJAX repose sur la création du modèle de localisation d'ASP.NET 2.0. Dans ce modèle, vous incorporez des fichiers de script et des ressources de script localisées selon une organisation « hub and spoke » d'assemblys (assemblys satellites). Vous pouvez utiliser ensuite de manière sélective ces scripts clients et ressources incorporés pour les langues et les régions spécifiques. Ce modèle permet à une base de code unique de prendre en charge plusieurs cultures. Cette dernière prend également en charge les fichiers de script localisés fournis en tant que fichiers .js sur le disque. ASP.NET peut traiter automatiquement des scripts clients et des ressources localisés pour des langues et des régions spécifiques.

Pour plus d'informations, consultez les rubriques suivantes :

Choix entre les fichiers de ressources globales et locales

Vous pouvez utiliser toute combinaison de fichiers de ressources globales et locales dans l'application Web. En général, vous ajoutez des ressources à un fichier de ressources globales lorsque vous souhaitez partager les ressources entre des pages. Les ressources dans les fichiers de ressources globales sont également fortement typées pour les accès aux fichiers par programme.

Toutefois, les fichiers de ressources globales peuvent devenir volumineux, si y vous stockez toutes les ressources localisées. Les fichiers de ressources globales peuvent également être plus difficiles à gérer, si plusieurs développeurs travaillent sur différentes pages dans un fichier de ressources unique.

Les fichiers de ressources locales simplifient la gestion des ressources pour une page Web ASP.NET seule. Mais vous ne pouvez pas partager les ressources entre les pages. En outre, vous pouvez créer de nombreux fichiers de ressources locales, si vous devez localiser un grand nombre de pages dans de nombreuses langues. Si les sites sont volumineux et comprennent de nombreux dossiers et langues, l'utilisation de ressources locales peut augmenter rapidement le nombre d'assemblys dans le domaine d'application.

Lorsque vous apportez une modification à un fichier de ressources par défaut, local ou global, ASP.NET recompile les ressources et redémarre l'application ASP.NET. Cela peut affecter les performances globales de votre site. L'ajout de fichiers de ressources satellites ne provoque pas la recompilation des ressources mais le redémarrage de l'application ASP.NET.

Remarque :
Les ressources liées sont prises en charge uniquement dans les fichiers de ressources globales.

Utilisation de ressources dans des pages Web

Après avoir créé des fichiers de ressources, vous pouvez les utiliser dans des pages Web ASP.NET. En général, vous utilisez des ressources pour remplir les valeurs de propriété de contrôles sur la page. Par exemple, vous pouvez utiliser des ressources pour définir la propriété Text d'un contrôle Button, au lieu de coder en dur la propriété en une chaîne spécifique.

Pour utiliser des ressources pour affecter des valeurs de propriété de contrôle, vous pouvez utiliser la localisation implicite ou explicite, comme suit :

La localisation implicite fonctionne avec les ressources locales et vous laisse affecter automatiquement à des propriétés de contrôle des ressources correspondantes.
La localisation explicite vous permet d'utiliser une expression de ressource pour affecter à une propriété de contrôle une ressource spécifique dans un fichier de ressources locales ou globales.

Localisation implicite avec des ressources locales

Si vous avez créé des fichiers de ressources locales pour une page spécifique, vous pouvez utiliser la localisation implicite pour remplir les valeurs de propriété pour un contrôle à partir du fichier de ressources. Avec la localisation implicite, ASP.NET lit un fichier de ressources et fait correspondre les ressources et les valeurs de propriété.

Pour utiliser la localisation implicite, vous devez utiliser une convention d'affectation de noms pour les ressources dans le fichier de ressources locales qui utilise le schéma suivant :

Key.Property

Par exemple, si vous créez des ressources pour un contrôle Button nommé Button1, vous pouvez créer les paires clé/valeur suivantes dans le fichier de ressources locales :

Button1.Text
Button1.BackColor
Label1.Text

Vous pouvez utiliser n'importe quel nom pour clé mais propriété doit correspondre au nom d'une propriété du contrôle que vous localisez.

Dans la page, vous utilisez un attribut meta spécial dans le balisage pour le contrôle pour spécifier la localisation implicite. Vous ne devez pas spécifier explicitement les propriétés localisées. Un contrôle Button qui est configuré pour la localisation implicite peut se présenter comme suit :

<asp:Button ID="Button1"  Text="DefaultText" 
    meta:resourcekey="Button1" />

La valeur resourcekey correspond à une clé dans le fichier de ressources correspondant. Au moment de l'exécution, ASP.NET fait correspondre les ressources aux propriétés de contrôle à l'aide de l'étiquette de contrôle en tant que resourcekey. Si une valeur de propriété est définie dans le fichier de ressources, ASP.NET substitue la valeur de ressource à la propriété.

Localisation explicite

Vous pouvez également utiliser la localisation explicite, dans laquelle vous utilisez une expression de ressource. Contrairement à localisation implicite, vous devez utiliser une expression de ressource pour chaque propriété que vous souhaitez définir.

Un contrôle Button qui est configuré pour définir la propriété Text à partir d'un fichier de ressources globales peut se présenter comme suit :

<asp:Button ID="Button1"  
    Text="<%$ Resources:WebResources, Button1Caption %>" />

L'expression de ressource prend la forme suivante, où Class est facultatif, à moins que la ressource ne soit globale et où ResourceID est requis :

<%$Ressources :Class,ResourceID%>

La valeur Class identifie le fichier de ressources à utiliser lorsque vous utilisez des ressources globales. Lorsque les fichiers .resx sont compilés, le nom de fichier de base, sans extension, est explicitement utilisé comme nom de classe de l'assembly résultant. Si vous souhaitez utiliser les ressources d'un fichier de ressources locales (fichier qui correspond au nom de la page active), vous n'avez pas besoin d'inclure de nom de classe. En effet, ASP.NET associe la classe de page à la classe de ressource.

La valeur ResourceID est l'identificateur de la ressource à lire. Dans l'exemple précédent, la propriété Text du bouton est lue à partir du fichier de ressources globales WebResources.resx (ou la version localisée appropriée). Dans ce fichier, ASP.NET utilise la valeur pour la ressource avec l'identificateur Button1Caption et pour la page elle-même. Pour définir des propriétés de page, vous pouvez utiliser des expressions de ressource @ Page dans la directive.

Vous pouvez spécifier une expression de ressource explicite ou implicite pour un contrôle, mais pas les deux. La syntaxe déclarative suivante d'un contrôle Button provoque une erreur d'analyse :

<asp:Button ID="Button1" 
             
            meta:resourcekey="Button1Resource1"
            Text="<%$ Resources:WebResources, Button1Caption %>" />

Dans cet exemple, un fichier de ressources locales implicite (fichier qui correspond au nom de la page active) est spécifié ainsi qu'un fichier de ressources explicite appelé WebResources. Pour éviter une erreur d'analyse pour ce contrôle, supprimez l'une des expressions de ressource.

Localisation de texte statique

Si une page comprend du texte statique, vous pouvez utiliser la localisation ASP.NET en l'incluant dans un contrôle Localize et utiliser ensuite la localisation explicite pour définir le texte statique. Le contrôle Localize ne restitue pas de balisage ; sa seule fonction est d'agir en tant qu'espace réservé pour du texte localisé. Le contrôle Localize peut être modifié en mode Design et non uniquement dans la grille des propriétés. Au moment de l'exécution, ASP.NET traite le contrôle Localize en tant que contrôle Literal. Par exemple, votre page peut inclure le code suivant :

<h1>
  <asp:Localize runat=server 
    ID="WelcomeMessage" 
    Text="Welcome!" meta:resourcekey="LiteralResource1" />
</h1>
<br />
<br />
<asp:Localize 
    ID="NameCaption"
    Text="Name: " meta:resourcekey="LiteralResource2" />
<asp:TextBox  ID="TextBox1" 
    meta:resourcekey="TextBox1Resource1" />

Note de sécurité :
Cet exemple a une zone de texte qui accepte l'entrée d'utilisateur, ce qui constitue une menace éventuelle pour la sécurité. Par défaut, les pages Web ASP.NET vérifient que les entrées d'utilisateur n'incluent pas de script ou d'éléments HTML. Pour plus d'informations, consultez Vue d'ensemble des attaques de script.

Localisation implicite dans les modèles

Dans les contrôles basés sur un modèle, tels que les contrôles DataList, GridView et Wizard, vous localisez les propriétés de style du modèle en accédant aux propriétés par le biais de l'expression de ressource implicite du contrôle parent. Vous ne pouvez pas utiliser d'expression de ressource implicite sur le modèle lui-même.

Pour localiser les valeurs d'une propriété de modèle, utilisez l'attribut meta et une clé de ressource pour le contrôle auquel le modèle appartient. Puis utilisez la syntaxe Property.Subproperty ou la syntaxe Property-Subproperty dans le fichier de ressources. Par exemple, la syntaxe déclarative suivante est valide pour un contrôle Wizard :

<asp:Wizard ID="Wizard1" 
     
    meta:resourcekey="Wizard1Resource1">
  <NavigationStyle 
    BorderWidth="<%$ resources:navBorderWidth %>"/>
  <WizardSteps>
    <asp:WizardStep ID="WizardStep1" 
       
      Title="Step 1" 
      meta:resourcekey="WizardStep1Resource1">
    </asp:WizardStep>
  </WizardSteps>
</asp:Wizard>

Les paires clé/valeur suivantes du fichier de ressources locales peuvent être utilisées pour l'exemple précédent :

Wizard1Resource1.NavigationStyle.BackColor, Red
navborderWidth, 5

Les paires clé/valeur suivantes pourraient également être utilisées :

Wizard1Resource1.NavigationStyle-BackColor, Red
navborderWidth, 5

Vous pouvez utiliser une expression de ressource explicite pour la propriété NavigationStyle du contrôle Wizard de l'exemple précédent. L'expression de ressource explicite omet le nom Class afin que les ressources d'un fichier de ressources local soient utilisées.

Pour plus d'informations sur les contrôles serveur basés sur des modèles, consultez Modèles de contrôles serveur Web ASP.NET.

Sélection de fichiers de ressources pour différentes langues

Lorsqu'une page s'exécute, ASP.NET sélectionne la version du fichier de ressources qui correspond le plus précisément au paramètre actuel UICulture de la page. S'il n'existe aucune correspondance, ASP.NET utilise le processus de secours des ressources pour obtenir une ressource. Par exemple, si vous exécutez la page Default.aspx et la propriété UICulture actuelle a la valeur es (Espagnol), ASP.NET utilise la version compilée du fichier de ressources locales Default.aspx.es.resx.

ASP.NET peut affecter aux propriétés UICulture et Culture pour la page la langue et les valeurs de culture qui sont passées par le navigateur. Vous pouvez également définir explicitement les propriétés UICulture et Culture, soit de manière déclarative ou dans le code. Vous pouvez également définir les valeurs de manière déclarative dans les fichiers Web.config. Pour plus d'informations, consultez Comment : définir la culture et la culture de l'interface utilisateur pour la globalisation des pages Web ASP.NET.

Remarque :
Vous ne devez pas compter exclusivement sur les paramètres de navigateur pour définir la langue et les informations de culture, car les utilisateurs peuvent utiliser un navigateur sur un ordinateur autre que le leur. En outre, les navigateurs ne communiquent fréquemment que des informations de langue sans définir de paramètre de culture précis. Dans ce cas, le serveur doit déduire une culture spécifique pour la mise en forme des données. Une bonne stratégie est de laisser les utilisateurs sélectionner explicitement une langue.

Vous ne devez pas compter exclusivement sur les paramètres de navigateur pour définir la langue et les informations de culture, car les utilisateurs peuvent utiliser un navigateur sur un ordinateur autre que le leur. En outre, les navigateurs ne communiquent fréquemment que des informations de langue sans définir de paramètre de culture précis. Dans ce cas, le serveur doit déduire une culture spécifique pour la mise en forme des données. Une bonne stratégie est de laisser les utilisateurs sélectionner explicitement une langue.

Utilisation des ressources par programme

Outre la définition de valeurs de la ressource dans le balisage avec les expressions de ressource, vous pouvez récupérer des valeurs de ressource par programme. Vous pouvez effectuer cette opération si la valeur de la ressource n'est pas connue au moment du design ou si vous souhaitez lui affecter une valeur obtenue au moment de l'exécution. Pour plus d'informations, consultez Comment : récupérer des valeurs de ressources par programme.

Voir aussi

Autres ressources

Globalisation et localisation ASP.NET