Localizing Resources for Component Libraries Overview
Localization is the process of customizing your application for a specific language and culture. Microsoft ASP.NET AJAX supports the following localization models for working with client script:
This topic contains the following information:
ASP.NET AJAX helps client localization for both page developers and component developers. Page developers will typically localize the following:
Exception messages that are generated from ASP.NET AJAX or component libraries, based on the browser’s language setting.
UI for controls, such as strings for the Text property of a Button control.
Values for public properties of ASP.NET AJAX server controls.
Values for properties of client script objects and components, such as non-visual components, behaviors, and controls.
Component developers will typically use localization features for the following:
Exposing localizable properties on server controls that are mapped to properties of client objects.
Localization is the process of customizing your application for a specific language and culture. ASP.NET AJAX builds on the ASP.NET 2.0 localization model and provides additional support for localized script files that are embedded in an assembly or are static .js files on disk.
If you are not familiar with the ASP.NET localization model, you can find information about it in the following topics:
The main assembly can also contain the resources for a single culture, which is referred to as the neutral or default culture. The neutral culture is the fallback culture for the application—that is, the culture settings that are used if no other culture is specified.
Localized resources for a culture are typically created as name/value pairs in .resx files. (These .resx files can also be compiled into .resources files.) The name provides a way to access the information in code, and the value is the localized (translated) term, image, or other element for that name. When an assembly is built, a type is generated for the .resx file in which the names are exposed as fields that provide programmatic access to the values. (You specify the name of this generated type as part of the assembly properties, as described later.)
In the hub-and-spoke model, each spoke connects to a satellite assembly that contains the resources for a single culture. The satellite assembly does not contain any code executed by the server. It contains only the generated type that provides programmatic access to the resource values for that culture.
This model offers the following features:
You can add resources for new cultures by deploying new satellite assemblies after you have already deployed an ASP.NET AJAX assembly. Developing culture-specific resources can require extra time. This model therefore enables you to release your main application first, and deliver additional culture-specific resources later.
You can update an application's satellite assemblies without recompiling your main assembly.
An application has to load only the satellite assembly for a particular culture, instead of unloading and reloading the main assembly. This can significantly reduce the use of system resources.
For information about how to create resource files for ASP.NET, see How to: Create Resource Files for ASP.NET Web Sites and Localizing ASP.NET Web Pages Using Resources.
For information about using the .NET Framework resource-file generator (Resgen.exe) tool, see Resource File Generator (Resgen.exe). This tool converts .resx or .txt files to binary .resources files that can be linked into assemblies.
Organizing Localized Main and Satellite Assemblies
The main assembly typically includes the following elements:
Optionally, the resources (.resx or .resources file) for a single neutral culture, which acts as the fallback culture for the application.
A satellite assembly typically includes localized resources for a single culture for the ASP.NET application. (No satellite assembly is required for the fallback culture.) The resources for a single culture are created in a separate resource file (.resx or .resources file) and then compiled into a single satellite assembly.
ASP.NET AJAX enables you to create your own custom culture and your own culture name. However, typically culture names are based on an ISO language code that consists of two letters for a language and two uppercase letters for a country or region. Examples include es-MX (Spanish, Mexico), es-CO (Spanish, Columbia), and fr-CA (French, Canada). For a complete list of culture names, see the CultureInfo class overview.
Names for Localized Embedded Script Files
The following naming convention is recommended for localized script files that are embedded as resources:
scriptname_noextension.[debug].[UI culture identifier].resources
The debug version of a file name includes ".debug" in the name. The release version does not.
The following table shows examples of this naming convention. These examples show both a release and debug version of an embedded script file followed by the associated release and debug versions of resources for those script files.
A release version of a neutral-culture script file, which is embedded in the main assembly.
A debug version of a neutral-culture script file, which is also embedded in the main assembly.
A release version of resources that are associated with the script file Sample.js, localized for a specific UI culture. These resources become part of the satellite assembly.
Debug-specific resources associated with the script file Sample.debug.js, localized for a specific UI culture. These resources become part of the satellite assembly that also includes the Sample.fr-FR.resources file.
This naming convention is not strictly required for script files that are embedded in assemblies or for resource files. This is because the mapping between the type generated for the resource and the resource name is accomplished by using an assembly attribute.
Localizing Debug Script Resources
If you are working in debug mode, at run time ASP.NET AJAX combines the release version of resources for script files with any additional debug resources. It then sends the resulting combination to the browser. Therefore, when you create resource files for debug versions of scripts, you have to define only the name/value pairs that are not already included in the release script resource files. By convention, debug versions of scripts and of script resources use the same name as their release counterpart but include ".debug" after the script file name.
Specifying Assembly Attributes for Localized Scripts and Localized Resources Associated with Scripts
To specify how resource files are managed when an assembly is built, you include attributes in the AssemblyInfo file (AssemblyInfo.vb or AssemblyInfo.cs file).
In Visual Studio, the AssemblyInfo.vb file is in the My Project node of Solution Explorer. If you do not see any files in the My Project node, in the Project menu, click Show All Files. The AssemblyInfo.cs file is in the Properties node of Solution Explorer.
The following example shows how to use assembly attributes to identify embedded scripts and their associated script resources.
' Indicates that neutral fallback resources are retrieved from
' the main assembly named MainAssembly.
' Defines embedded scripts as Web resources.
' Defines the script resources for the scripts and their types.
// Indicates that neutral fallback resources are retrieved from
// the main assembly named MainAssembly.
// Defines embedded scripts as Web resources.
// Defines the script resources for the scripts and their types.
In this example, a main assembly named MainAssembly contains an embedded release version of a client script file that is named Sample.js. The assembly also contains the corresponding debug version named Sample.debug.js. The .js files are identified as resources by the WebResourceAttribute attribute.
The NeutralResourcesLanguageAttribute assembly attribute is used to specify the main assembly as the fallback culture. For more information, see Neutral Resources Languages for Localization and the NeutralResourcesLanguageAttribute class overview.
The resources used by the script files are defined by using the ScriptResourceAttribute attribute. The Sample.resources and Sample.debug.resources files contain resource values for the Sample.js and Sample.debug.js files, respectively.
For more information about how to create assembly-information files and the assembly metadata that is required for versioned assemblies, see How to: Create Versioned Assemblies for Precompiled Web Sites.
You can organize a script library as localized static script files (.js files) on disk instead embedding the script files in assemblies. Page developers can reference the script files through the ScriptReferenceCollection class.
Localized Debug Scripts in the Static Script File Model
In the static script file model, localized resources that a script refers to are typically defined as a type in a single .js file. A debug version of a script file is organized in the same way, with both localized release resources and additional debug resources defined as a type in a single file. Debug versions of scripts use the same name as the corresponding release version, but include ".debug" after the name.
You can use the ScriptManager control to manage static scripts that are located in a central directory on disk. To do so, put all versions of the script files in one folder, including release and debug versions of all localized files. The following example shows the layout of a directory structure for a static script file library:
In this example, all the script files are in a folder that is named by using the script library version (184.108.40.206). This version-specific folder is in turn in a folder that is named after the library's namespace. Organizing a script library within folders by namespace and version can provide some version control for your library and it can help you avoid script-name collisions between libraries. It also enables consumers of your library to identify what library and library version the files belong to.
The ScriptManager control provides the following functionality for using localized scripts and script resources:
Enables you to define which UI cultures are supported, which includes custom UI cultures.
Interprets the culture-specific assembly attribute and automatically detects the UI culture of the browser (if any), and then reads the localized or fallback scripts and resources from the assembly. In debug mode, it tries to load a script resource that contains both the appropriate UI culture name and the string ".debug" in the file name, such as Sample.debug.fr-FR.resources.
Generates URLs that point to the appropriate scripts and to their localized resources. For added security, it encrypts the URLs.
Determines whether a script or script resource will be compressed, based on a parameter in the generated URL.
Adds a timestamp to the assembly that contains embedded scripts so that the browser does not indefinitely cache the scripts.
For more information, see the ScriptManager class overview.
The following example shows part of a Web page that uses the ScriptManager control to register a client control that is located in an assembly. The embedded script is registered by using the Assembly and Name properties.
<%@ Register TagPrefix="Samples" Namespace="DemoControls"
Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<form id="form1" runat="server">
<asp:ScriptManager ID="ScriptManager1" runat="server">
<!-- Additional markup here. -->
How-to and Walkthrough Topics
The following table lists the key classes that are used for localizing component libraries.
Manages ASP.NET 2.0 AJAX Extensions components, partial-page rendering, client requests, and server responses on ASP.NET server pages.
Provides access to ScriptReference objects that represent client script files.