Creating a Custom Localization

In this tutorial, you will learn how to add custom localization to AJAX Control Toolkit. To learn how to install the toolkit, see the Step-by-Step Installation Guide page.

Add JavaScript files with localization resources

A localization file contains a JavaScript hash object named

Sys.Extended.UI.Localization["<localeKey>"]

<localeKey> is the name of a locale for which you are providing resources.

For the Russian locale, this object is named

Sys.Extended.UI.Localization["ru"]

The hash object structure matches the structure in built-in localization files and contains a subset of the Sys.Extended.UI.Resources hash object (defined in AjaxControlToolkit.Scripts.Localization.Resources.js) with key-value pairs that should be overridden for a particular culture.

For example, if you want to localize only the Calendar_Today entry, your hash object will contain a single entry with the Calendar_Today key and a value with a translation for your locale.

JavaScript files can be have two variants: a debug and release version. A debug version ends with .js, while a release version ends with .min.js To make a minified version of a JavaScript file, use the Web Essentials (Visual Studio 2013 or earlier) or Bundler & Minifier extension (Visual Studio 2015).

Mark localization files as Embedded Resource

Localization files will be stored in your assembly, so you don’t need to write any custom HTTP-handlers to retrieve them. Set these files’ Build Action to Embedded Resource.

Add WebResource attribute for every localization file

Storing resources in an assembly does not mean that they will be available outside this assembly by default. To expose any embedded resource to web clients, you need to add the WebResource attribute for every localization file. This attribute is applied to an assembly scope.

The attribute constructor requires two parameters:

webResource is the name of a Web resource embedded into an assembly.

contentType is the type of a resource, such as "image/gif" or "text/javascript".

For example, if you have embedded resources into an assembly named MyAssembly.MyLocalization.js and MyAssembly.MyLocalization.min.js, the attributes will be as follows:

[assembly: WebResource("MyAssembly.MyLocalization.js", "text/javascript")]
[assembly: WebResource("MyAssembly.MyLocalization.min.js", "text/javascript")]

Register custom localization

Custom localizations are registered with the Localization.AddLocale() static method, which requires three attributes:

localeKey is a locale name, like “en”, “de”, “fr”, etc.

scriptName is a JavaScript localization file name without an extension.

scriptAssembly is an assembly that contains a localization file.

For example, registering MyAssembly.MyLocalization.js for the Italian locale will be as follows:

Localization.AddLocale("it", "MyAssembly.MyLocalization", Assembly.GetExecutingAssembly());

This method can be called anytime, but the most convenient place is the Application_Start() method in the Global.asax file.

Overriding built-in localizations

You can override any localization that is built into AJAX Control Toolkit with your custom localization by providing the same localeKey when calling the Localization.AddLocale() method.

For example, if you want to override the Korean localization, pass “ko” as the first parameter:

Localization.AddLocale("ko", "MyAssembly.MyLocalization", Assembly.GetExecutingAssembly());