ASP.NET Ajax

ASP.NET Ajax Tutorial Lesson 10: Localization and Globalization

Support for globalization in ASP.NET Ajax is controlled by the EnableScriptGlobalization property of the ScriptManager object, which by default is set to false. When this is set to true, the client-side classes Date and Number expose the localeFormat() method, which returns appropriately globalized strings on the client.

For example, suppose that you’re working with the following function, which puts up an alert box with today’s date.

1.	function alertDate()
2.	{
3.	var d = new Date();
4.	alert(d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss"));
5.	}

When I cause this function to be run in my browser, I get the following result.

However, if I change the page culture (by setting culture="fr-CA" on the @Page directive) and run the function again, I get this instead:

Moving to script localization (ie. using appropriate string resources), things become more complicated. There are two models for localizing scripts, the static and the dynamic.

ASP.NET allows one to embed arbitrary types of file within an assembly, and handles the plumbing required to expose these files to a web page, with appropriate caching. In particular, it is possible to embed javascript files in this way, and much of ASP.NET Ajax is built on this functionality. The ‘dynamic’ model of localization uses this embedding functionality, but the ‘static’ model deals with javascript files in the usual way. We turn to this first.

In the static model of localization you use as many javascript files as cultures you wish to support. These files need to be named using the standard convention for localization, with the culture tag as part of the name. The following example will make this clear.

Suppose that we want to have a script file which explicitly supports the French-Canadian culture. Then we might have a folder containing the following two files:

So that the script manager knows to load up this script, we place an script reference in its ‘scripts’ property. So that it knows to load up the right version of the script we also turn on the ‘EnableScriptGlobalization’ switch, and mark the fact that we have a French-Canadian version of the script via the ResourceUICultures property:

1.	<asp:ScriptManager enablescriptglobalization=true ID="ScriptManager1" runat="server" >
2.	<scripts>
3.	<asp:scriptreference path="scripts/myJS.js" ResourceUICultures="fr-CA"/>
4.	</scripts>
5.	</asp:ScriptManager>

When we set the UICulture of the page to ‘fr-CA’, the script manager object then automatically references the myJS.fr-CA.js file.

Dynamic localization, by contrast, makes use of the standard ASP.NET localization functionality, in which appropriate XML resource files are selecteded based on the page UICulture. Dynamic localization involves the use of only one source script file, but appropriate parts of an XML resource file is interpolated into the script returned from this source. The example should make this clear.

Suppose that we have a script file test.js with the code

1.	function alertSomething()
2.	{
3.	alert(Default.TestName);
4.	}

The term ‘Default.TestName’ here is a placeholder which we want to be replaced by the value from an appropriate resources file.

The first thing to do is to setup the test.js file as a web resource, which as noted above is functionality built into ASP.NET proper. To do this we first specify that the test.js file is embedded within the assembly (in Studio this is easy – just go to the properties of the file and change the Build Action to ‘embedded resource’). Then we add the following assembly-level declaration (which can be placed within a page):

[assembly: WebResource("FunWithAjax.test.js", "application/x-javascript")]

Note that in this context the name of the file is qualified with the name of the project.

We then tell the script manager for the appropriate page that we want to output this javascript file. As before, this involves setting a script reference, viz:

1.	<scripts>
2.	<asp:scriptreference assembly="FunWithAjax" name="FunWithAjax.test.js" ignorescriptpath=true />
3.	</scripts>

Note that in this case we specify the assembly and resource name rather than a simple path.

So far this is sufficient to output the test.js file, but it will be output with the reference to Default.TestName intact. To wire up the resource-string-interpolation we first need to have a resource file with a ‘TestName’ element, say TestResources.resx. We then add the following declaration:

[assembly: ScriptResource("FunWithAjax.test.js", "FunWithAjax.TestResources", "Default")]

This identifies the embedded script file, the resource file you want it to be mapped to, and a name for the mapping. Since the name is ‘Default’, and the resource file contains an element called ‘TestName’, the element ‘Default.TestName’ in the script is mapped to the correponding value in the resource file.

Given this setup, to localize the script relative to an appropriate culture you simply need to add an appropriately relativised resource file.