Localizing Resources for Component Libraries Overview
Localization is the process of customizing an application for a specific language and culture. The AJAX functionality in ASP.NET supports the following localization models for working with client script:
This topic contains the following information:
Localizing Client Scripts and Script Resources in Assemblies
Localizing Static Script Files and Their Resources
Using ScriptManager to Manage Scripts in a Central Location
AJAX features in ASP.NET help client localization for both page developers and component developers. Page developers typically localize the following:
Exception messages that are generated from ASP.NET AJAX or from component libraries, based on the browser’s language setting.
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 typically use localization features for the following:
Exposing localizable properties of server controls that are mapped to properties of client objects.
AJAX functionality in ASP.NET builds on the ASP.NET 2.0 localization model. It 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:
Localizing Client Script Files and Script Resources in Assemblies
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. It is used if no culture is specified or if there are no resources for the specified culture.
Localized resources for a culture are typically created as name/value pairs in .resx files. (These .resx files can be compiled into .resources files.) The name provides access to 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 that is 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 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 By Using Resources.
For information about how to use the .NET Framework resource-file generator (Resgen.exe) tool, see Resgen.exe (Resource File Generator). 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 enables you to create a custom UI culture and a custom 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 System.Globalization.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|resx]
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. The examples show a release and debug version of an embedded script file. They also show 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 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, for projects written in Visual Basic, 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. For projects written in C#, 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.
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 System.Resources.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 Site Projects.
Localizing Static Script Files and Their Resources
You can organize a script library as localized static script files (.js files) on disk instead of 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.
Using ScriptManager to Manage Scripts
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, which includes 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 (188.8.131.52). 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. It can also help you avoid script-name collisions between libraries. In addition, it enables consumers of your library to identify what library and library version the files belong to.
Understanding the Role of the ScriptManager Control in Localization
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). It 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" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head runat="server"> <title>ScriptReference</title> </head> <body> <form id="form1" runat="server"> <div> <asp:ScriptManager ID="ScriptManager1" runat="server"> <Scripts> <asp:ScriptReference Assembly="SampleAssembly" Name="DemoControls.SampleControl.js" /> </Scripts> </asp:ScriptManager> <!-- Additional markup here. --> </div> </form> </body>
How-to and Walkthrough Topics
The following table lists the key classes that are used for localizing component libraries.
Manages AJAX components, partial-page rendering, client requests, and server responses on ASP.NET server pages.