Vue d'ensemble de la localisation de ressources pour les bibliothèques de composants

Article
10/22/2014

Mise à jour : novembre 2007

La localisation est le processus de personnalisation d'une application pour une langue et une culture spécifiques. Les fonctionnalités AJAX d'ASP.NET prennent en charge les modèles de localisation suivants permettant d'utiliser un script client :

Le modèle de ressources du .NET Framework, avec prise en charge étendue des ressources localisées associées à vos composants ECMAScript (JavaScript). Dans ce modèle, vous avez incorporé des fichiers de script et localisé des ressources de script selon une organisation « hub and spoke » d'assemblys (autrement dit, vous utilisez des 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.
Fichiers JavaScript statiques (autonomes) sur le disque. Dans ce modèle, les fichiers localisés sont regroupés au sein d'un répertoire unique en tant que fichiers .js et non pas incorporés dans un assembly.
Mise à jour de scripts et de ressources de script incorporés dans un assembly à l'aide de fichiers statiques JavaScript. Ce modèle vous permet de fournir une prise en charge supplémentaire de localisation pour les scripts et les ressources incorporés, sans nécessiter l'apport de modifications à l'assembly d'origine.

Cette rubrique contient les informations suivantes :

Scénarios
Contexte
Localisation de scripts et de ressources de script dans des assemblys
Localisation de fichiers de script statiques et de leurs ressources
Utilisation de ScriptManager pour gérer des scripts dans un emplacement central
Exemples de code
Référence de Classe

Scénarios

Les fonctionnalités AJAX d'ASP.NET contribuent à la localisation cliente pour les développeurs de pages et les développeurs de composants. En général, les développeurs de pages localisent les éléments suivants :

Messages d'exception générés à partir d'ASP.NET AJAX ou de bibliothèques de composants, en fonction du paramètre de langue du navigateur.
Interface utilisateur pour les contrôles tels que les chaînes pour la propriété Text d'un contrôle Button.
Valeurs de propriétés publiques de contrôles serveur ASP.NET AJAX ;
Valeurs de propriétés d'objets et de composants de script client tels que les composants, les comportements et les contrôles non visuels.

En général, les développeurs de composants utilisent des fonctionnalités de localisation pour les éléments suivants :

Localisation des ressources référencées dans le code des bibliothèques JavaScript (fichiers .js). Les ressources localisées peuvent être déployées dans des installations distinctes, sans que l'assembly principal ou la bibliothèque de scripts ne soit régénéré.
Exposition de propriétés localisables de contrôles serveur mappées à celles d'objets clients.

Contexte

Les fonctionnalités AJAX d'ASP.NET reposent sur le modèle de localisation d'ASP.NET 2.0. Il fournit la prise en charge supplémentaire pour des fichiers de script localisés incorporés dans un assembly ou des fichiers .js statiques sur le disque.

Si vous n'êtes pas familiarisé avec le modèle de localisation ASP.NET, vous pouvez trouver des informations sur ce sujet dans les rubriques suivantes :

Localisation de fichiers de script client et de ressources de script dans des assemblys

Les fonctionnalités AJAX d'ASP.NET tirent parti du modèle de ressources du .NET Framework pour la localisation. Ce modèle utilise une disposition « hub and spoke » pour empaqueter et déployer des ressources localisées qui peuvent être mises à jour de façon incrémentielle. Le « hub » est l'assembly principal qui contient le code exécutable non localisé. Il inclut à la fois le code serveur du .NET Framework et n'importe quel code JavaScript présent dans des fichiers .js incorporés en tant que ressource dans l'assembly.

L'assembly principal peut également contenir les ressources pour une culture unique, appelée culture neutre ou par défaut. La culture neutre est la culture de secours pour l'application. Elle est utilisée si aucune culture n'est spécifiée ou s'il n'existe aucune ressource pour la culture spécifiée.

Les ressources localisées pour une culture sont généralement créées en tant que paires nom/valeur dans les fichiers .resx. (Ces fichiers .resx peuvent être compilés dans des fichiers .resources.) Le nom fournit l'accès aux informations du code. De plus, la valeur est le terme, l'image ou un autre élément localisé (traduit) pour ce nom. Lors de la génération d'un assembly, un type est créé pour le fichier .resx dans lequel les noms sont exposés en tant que champs qui fournissent un accès par programme aux valeurs. (Vous spécifiez le nom de ce type créé dans le cadre des propriétés de l'assembly, comme décrit ultérieurement.)

Dans le modèle « hub and spoke », chaque « spoke » se connecte à un assembly satellite qui contient les ressources pour une culture unique. L'assembly satellite ne contient pas de code exécuté par le serveur. Il ne contient que le type créé qui fournit un accès par programme aux valeurs de ressources de cette culture.

Ce modèle offre les fonctionnalités suivantes :

Pour ajouter des ressources pour de nouvelles cultures, vous pouvez déployer de nouveaux assemblys satellites après avoir déployé un assembly. Le développement de ressources spécifiques à la culture peut nécessiter du temps supplémentaire. Ainsi, ce modèle vous permet de libérer d'abord votre application principale et de fournir ultérieurement d'autres ressources spécifiques à la culture.
Vous pouvez mettre à jour et changer les assemblys satellites d'une application sans recompiler votre application principale.
Une application ne doit charger que l'assembly satellite d'une culture particulière, et non pas décharger puis recharger l'assembly principal. Cela peut diminuer de manière importante l'utilisation des ressources système.

Pour plus d'informations sur la création de fichiers de ressources pour ASP.NET, consultez Comment : créer des fichiers de ressources pour des sites Web ASP.NET (Visual Studio) et Localisation de pages Web ASP.NET à l'aide de ressources.

Pour plus d'informations sur l'utilisation de l'outil Resource File Generator Tool (Resgen.exe) du .NET Framework, consultez Outil Resource File Generator Tool (Resgen.exe). Cet outil convertit les fichiers .resx ou .txt en fichiers .resources binaires qui peuvent être liés entre eux pour former des assemblys.

Organisation d'assemblys principaux et satellites localisés

Vous pouvez utiliser le modèle « hub and spoke » lorsque vous souhaitez localiser une application qui inclut des fichiers JavaScript (.js). En général, vous organisez l'assembly comme vous le feriez pour n'importe quelle application ASP.NET localisée.

Pour gérer les fichiers JavaScript pour une application Web ASP.NET AJAX, vous écrivez du code JavaScript afin qu'il ne code pas en dur des chaînes ou autres éléments qui doivent être localisés. Au lieu de cela, vous obtenez un champ du type généré à l'extérieur du fichier de ressources dans tous les emplacements où le code JavaScript doit utiliser des valeurs localisées.

En général, l'assembly principal inclut les éléments suivants :

Fichiers JavaScript qui exécutent les tâches d'application et qui sont écrits pour utiliser les ressources localisées au lieu de celles codées en dur. L'assembly peut éventuellement inclure des versions Debug de ces fichiers JavaScript.
Éventuellement, les ressources (fichier .resx ou .resources) pour une culture neutre unique, qui agit comme la culture de secours pour l'application.
Facultativement, n'importe quelle version Debug de ressources de culture neutre. La version Debug d'un fichier de ressources inclut toutes les paires nom/valeur supplémentaires requises pour les versions Debug des fichiers JavaScript.

En général, un assembly satellite inclut des ressources localisées d'une culture unique pour l'application ASP.NET. (Aucun assembly satellite n'est requis pour la culture de secours.) Les ressources d'une culture unique sont créées dans un fichier de ressources distinct (fichier .resx ou .resources), puis compilées dans un assembly satellite unique.

Remarque :
ASP.NET vous permet de créer une culture d'interface utilisateur et un nom de culture personnalisés. Cependant, les noms de cultures reposent généralement sur un code de langue ISO qui se compose de deux lettres pour une langue et de deux majuscules pour un pays ou une région. es-MX (espagnol, Mexique), es-CO (espagnol, Colombie) et fr-CA (français, Canada), par exemple. Pour obtenir une liste complète de noms de cultures, consultez la vue d'ensemble de la classe System.Globalization.CultureInfo.

ASP.NET vous permet de créer une culture d'interface utilisateur et un nom de culture personnalisés. Cependant, les noms de cultures reposent généralement sur un code de langue ISO qui se compose de deux lettres pour une langue et de deux majuscules pour un pays ou une région. es-MX (espagnol, Mexique), es-CO (espagnol, Colombie) et fr-CA (français, Canada), par exemple. Pour obtenir une liste complète de noms de cultures, consultez la vue d'ensemble de la classe System.Globalization.CultureInfo.

Noms de fichiers de script incorporés localisés

La convention d'affectation de noms suivante est recommandée pour les fichiers de script localisés incorporés en tant que ressources :

scriptname_noextension.[debug].[UI culture identifier].[resources|resx]

La version Debug d'un nom de fichier inclut « .debug » dans le nom contrairement à la version Release.

Le tableau suivant présente des exemples de convention d'affectation de noms. Ces exemples présentent une version Release et Debug d'un fichier de script incorporé. Ils affichent également les versions Release et Debug associées de ressources pour ces fichiers de script.

Sample.js
Version Release d'un fichier de script d'une culture neutre, incorporé dans l'assembly principal.
Sample.debug.js
Version Debug d'un fichier de script d'une culture neutre, également incorporé dans l'assembly principal.
Sample.fr-FR.resources
Version Release de ressources associées au fichier de script Sample.js, localisées pour une culture d'interface utilisateur spécifique. Ces ressources font partie intégrante de l'assembly satellite.
Sample.debug.fr-FR.resources
Ressources spécifiques à Debug associées au fichier de script Sample.debug.js, localisées pour une culture d'interface utilisateur spécifique. Ces ressources font partie intégrante de l'assembly satellite qui inclut également le fichier Sample.fr-FR.resources.

Cette convention d'affectation de noms n'est pas strictement requise pour les fichiers de script incorporés dans des assemblys ou pour des fichiers de ressources. Cela est dû à l'exécution du mappage entre le type généré pour la ressource et le nom de la ressource à l'aide d'un attribut d'assembly.

Localisation de ressources de script de débogage

Si vous travaillez en mode débogage lors de l'exécution, ASP.NET combine la version Release de ressources pour les fichiers de script à l'aide de toutes les ressources Debug supplémentaires. Il envoie ensuite la combinaison obtenue au navigateur. Par conséquent, lorsque vous créez des fichiers de ressources pour des versions Debug de scripts, vous ne devez définir que les paires nom/valeur qui ne sont pas déjà incluses aux fichiers de ressources de scripts Release. Par convention, les versions Debug de scripts et de ressources de script utilisent le même nom que leur contrepartie Release mais incluent « .debug » après le nom du fichier de script.

Spécification d'attributs d'assembly pour des scripts localisés et des ressources localisées associées à des scripts

Pour spécifier le mode de gestion des fichiers de ressources lors de la génération d'un assembly, vous pouvez inclure des attributs dans le fichier AssemblyInfo (fichier AssemblyInfo.vb ou AssemblyInfo.cs).

Remarque :
Dans Visual Studio, pour les projets écrits en Visual Basic, le fichier AssemblyInfo.vb se trouve dans le nœud My Project de l'Explorateur de solutions. Si vous ne voyez pas de fichiers dans le nœud My Project, dans le menu Projet, cliquez sur Afficher tous les fichiers. Pour les projets écrits en C#, le fichier AssemblyInfo.cs se trouve dans le nœud Propriétés de l'Explorateur de solutions.

Dans Visual Studio, pour les projets écrits en Visual Basic, le fichier AssemblyInfo.vb se trouve dans le nœud My Project de l'Explorateur de solutions. Si vous ne voyez pas de fichiers dans le nœud My Project, dans le menu Projet, cliquez sur Afficher tous les fichiers. Pour les projets écrits en C#, le fichier AssemblyInfo.cs se trouve dans le nœud Propriétés de l'Explorateur de solutions.

Dans ASP.NET, marquez les ressources pour l'application à l'aide de la classe WebResourceAttribute. Pour incorporer des fichiers JavaScript dans un assembly, utilisez cet attribut pour spécifier les fichiers .js en tant que ressource Web.

Pour inclure des fichiers de ressources pour les fichiers JavaScript incorporés, utilisez la classe ScriptResourceAttribute. Cet attribut identifie spécifiquement les ressources basées sur du texte comme ressources pour les fichiers JavaScript.

Remarque :
La classe ScriptResourceAttribute ne peut être utilisée que pour identifier des ressources basées sur du texte pour les fichiers JavaScript. Pour associer un fichier image (binaire) localisé dans une culture, stockez son URL en tant que ressource localisée que le script peut résoudre et charger.

L'exemple suivant montre comment utiliser des attributs d'assembly pour identifier des scripts incorporés et leurs ressources de script associées.

' Indicates that neutral fallback resources are retrieved from 
' the main assembly named MainAssembly.
<assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)>

' Defines embedded scripts as Web resources.
<assembly:WebResource("Sample.js", "text/javascript")>
<assembly:WebResource("Sample.debug.js", "text/javascript")>

' Defines the script resources for the scripts and their types.
<assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")>
<assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")>

// Indicates that neutral fallback resources are retrieved from 
// the main assembly named MainAssembly.

[assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)]

// Defines embedded scripts as Web resources.
[assembly:WebResource("Sample.js", "text/javascript")]
[assembly:WebResource("Sample.debug.js", "text/javascript")]

// Defines the script resources for the scripts and their types.
[assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")]
[assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")]

Dans cet exemple, un assembly principal nommé MainAssembly contient une version Release intégrée d'un fichier de script client, appelée Sample.js. L'assembly contient également la version Debug correspondante nommée Sample.debug.js. Les fichiers .js sont identifiés en tant que ressources par l'attribut WebResourceAttribute.

L'attribut d'assembly NeutralResourcesLanguageAttribute permet de spécifier l'assembly principal en tant que culture de secours. Pour plus d'informations, consultez Langues des ressources neutres pour la localisation et la vue d'ensemble de la classe System.Resources.NeutralResourcesLanguageAttribute.

Les ressources utilisées par les fichiers de script sont définies via l'utilisation de l'attribut ScriptResourceAttribute. Les fichiers Sample.resources et Sample.debug.resources contiennent respectivement des valeurs de ressources pour les fichiers Sample.js et Sample.debug.js.

Un type nommé Sample.Res est à la fois généré pour la version Release et Debug des ressources de script. Il s'agit du type que le code JavaScript utilise pour accéder aux valeurs localisées. Pour les modes Release et Debug, le processus de génération ne crée qu'un type unique. En mode débogage, les ressources pour la version Release sont combinées avec les ressources supplémentaires pour la version Debug.

Pour plus d'informations sur la création de fichiers d'informations d'assembly et de métadonnées de l'assembly requis pour les assemblys dont la version est gérée, consultez Comment : créer des assemblys dont la version est gérée pour les sites Web précompilés.

Localisation de fichiers de script statiques et de leurs ressources

Vous pouvez organiser une bibliothèque de scripts en tant que fichiers de script statiques localisés (fichiers .js) sur le disque, au lieu d'incorporer les fichiers de script dans des assemblys. Les développeurs de pages peuvent référencer les fichiers de script via la classe ScriptReferenceCollection.

Dans le modèle de fichier de script statique, il n'existe aucun fichier distinct .resx ou .resources qui peut être automatiquement géré en tant que ressources pour les fichiers JavaScript. Au lieu de cela, il n'existe que des fichiers .js, un pour chaque culture d'interface utilisateur et combinaison de paramètres régionaux. En effet, chaque fichier .js représente une version spécifique aux paramètres régionaux du code JavaScript complet. L'une des méthodes standard pour gérer des fichiers de script localisés dans ce modèle consiste à utiliser la même logique JavaScript dans chaque fichier .js. Comme dans le modèle incorporé dans l'assembly, le code JavaScript appelle un type pour récupérer des valeurs de ressources localisées. La différence est que vous devez fournir le type qui contient les valeurs localisées ; il n'est pas généré automatiquement. Par exemple, le fichier .js pour chaque paramètre régional peut inclure à la fois le code d'application et une classe qui définit les champs qui contiennent des valeurs localisées. Dans chaque fichier .js, cette classe contient des valeurs dans une langue différente.

Remarque :
Dans le modèle de fichier de script statique, le code d'application JavaScript des fichiers .js peut ne pas être synchronisé avec celui du fichier JavaScript incorporé. Cela tient au fait que chaque fichier de script inclut une copie du code. Pour éviter les problèmes de contrôle de version avec du code dupliqué, vous pouvez conserver un exemplaire unique des fichiers JavaScript sources et créer des types de ressources localisés dans des fichiers distincts. Vous pouvez alors générer les fichiers combinés finaux lors du processus de génération de votre application.

Dans le modèle de fichier de script statique, le code d'application JavaScript des fichiers .js peut ne pas être synchronisé avec celui du fichier JavaScript incorporé. Cela tient au fait que chaque fichier de script inclut une copie du code. Pour éviter les problèmes de contrôle de version avec du code dupliqué, vous pouvez conserver un exemplaire unique des fichiers JavaScript sources et créer des types de ressources localisés dans des fichiers distincts. Vous pouvez alors générer les fichiers combinés finaux lors du processus de génération de votre application.

Les fichiers de script statiques localisés sont mappés à leur culture d'interface utilisateur en incluant le nom de culture d'interface utilisateur au nom du fichier, ainsi que des ressources incorporées dans un assembly. Par exemple, un fichier de script client incorporé culturellement neutre pour le français se nomme Sample.fr.js et une ressource JavaScript spécifique à la culture pour le français (Canada) se nomme Sample.fr-CA.js.

Scripts de débogage localisés dans le modèle de fichier de script statique

Dans le modèle de fichier de script statique, les ressources localisées auxquelles se réfère un script sont généralement définies en tant que type dans un fichier .js unique. Une version Debug d'un fichier de script est organisée de la même manière, à la fois avec des ressources Release localisées et des ressources Debug supplémentaires définies en tant que type dans un fichier unique. Des versions Debug de scripts utilisent le même nom que la version Release correspondante, mais incluent « .debug » après le nom.

Utilisation de ScriptManager pour gérer des scripts

Vous pouvez utiliser le contrôle ScriptManager pour gérer des scripts statiques situés dans un répertoire central sur le disque. Pour ce faire, placez toutes les versions des fichiers de script dans un dossier, qui inclut les versions Release et Debug de tous les fichiers localisés. L'exemple suivant présente l'organisation d'une structure de répertoires pour une bibliothèque de fichiers de script statiques :

SampleNamespace/

1.0.0.0/

Sample.js

Sample.debug.js

Sample.de-DE.js

Sample.debug.de-DE.js

Sample.fr-FR.js

Sample.debug.fr-FR.js

Dans cet exemple, tous les fichiers de script se trouvent dans un dossier nommé à l'aide de la version de la bibliothèque de scripts (1.0.0.0). Ce dossier spécifique à la version se trouve dans un dossier nommé d'après l'espace de noms de la bibliothèque. L'organisation d'une bibliothèque de scripts dans des dossiers par espace de noms et version peut fournir un contrôle de version pour votre bibliothèque. Elle peut également vous aider à éviter des collisions script-nom entre plusieurs bibliothèques. De plus, elle permet aux utilisateurs de votre bibliothèque d'identifier la bibliothèque et la version de la bibliothèque à laquelle appartiennent les fichiers.

Fonctionnement du rôle du contrôle ScriptManager au cours de la localisation

Le contrôle ScriptManager fournit les fonctionnalités suivantes pour utiliser des scripts localisés et des ressources de script :

Vous permet de définir les cultures d'interface utilisateur prises en charge, qui incluent des cultures d'interface utilisateur personnalisées.
Interprète l'attribut d'assembly spécifique à la culture et détecte automatiquement la culture d'interface utilisateur du navigateur (le cas échéant). Il lit ensuite les scripts et les ressources localisés ou de secours à partir de l'assembly. En mode Debug, il tente de charger une ressource de script qui contient à la fois le nom de culture d'interface utilisateur approprié et la chaîne « .debug » dans le nom de fichier tel que Sample.debug.fr-FR.resources.
Génère des URL qui pointent vers les scripts appropriés et leurs ressources localisées. Pour renforcer encore la sécurité, il chiffre les URL.
Détermine si un script ou une ressource de script sera compressée, en fonction d'un paramètre de l'URL générée.
Ajoute un horodateur à l'assembly qui contient des scripts incorporés afin que le navigateur ne mette pas en cache les scripts indéfiniment.

Pour plus d'informations, consultez la vue d'ensemble de la classe ScriptManager.

L'exemple suivant présente une partie de page Web qui utilise le contrôle ScriptManager pour inscrire un contrôle client situé dans un assembly. Le script incorporé est inscrit à l'aide des propriétés Assembly et Name.

<%@ Register TagPrefix="Samples" Namespace="DemoControls" 
  Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head >
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" >
    <div>
      <asp:ScriptManager ID="ScriptManager1" >
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

    </div>
  </form>
</body>

Exemples de code

Les sections suivantes incluent des exemples de code qui montrent comment utiliser des fichiers et des ressources JavaScript.

Rubriques "Comment" et "Procédure pas à pas"

Référence de Classe

Le tableau suivant répertorie les classes clés utilisées pour localiser des bibliothèques de composants.

ScriptManager
Gère des composants AJAX, le rendu de page partielle, les requêtes du client et les réponses du serveur sur les pages serveur ASP.NET.
ScriptReference
Fournit des API pour inscrire des fichiers JavaScript à utiliser dans une page Web (fichiers incorporés dans un assembly ou situés sur le disque).
ScriptReferenceCollection
Fournit un accès aux objets ScriptReference qui représentent les fichiers de script client.

Voir aussi