Localizing XML Templates

In the section discussing Core XML Template Elements, you have been introduced to two localization-related elements that you can use in XML templates on a website that has multiple-language versions (localizations).

In addition, you can use an ad-hoc package that provides functionality to automatically localize strings in XML templates.

Let’s take a look at these options. It makes sense, however, to start from the information on the resource files, their content and on how their content can be used for localization.

Using Resource Files for Localization

C1 CMS makes use of a standard .NET resource file to keep the localization data centrally, in one place. The use of resource files is not C1 CMS template-specific; however, we will focus on using resource files for C1 CMS templates here.

If you run two language versions of your website, you might want to have strings used within XML templates in those two languages. And when the user opens a page in one of the languages, he or she can see these strings in the correct language.

To start using localized version of a string you need:

• A kind of variable that you use instead of the string in one of the languages
• A list of matches between these variables and their values – strings - in the corresponding language

It makes sense to have a separate list for each language.

When the user opens a page in one of the languages used on the website, the system looks for these “localization” variables in the currently used template, reads their values from the list that matches the current language and replaces the variable with the string value - and the user can see the text in the language of the localized website.

The .NET resource file contains this list in XML format. Here is the sample of such a list in the resource file:

<root>
  <!-- skipped -->
  <data name="Hello" xml:space="preserve">
    <value>Hello</value>
  </data>
  <data name="HelloScandinavia" xml:space="preserve">
    <value>Hello Scandinavia</value>
  </data>
  <data name="HelloWorld" xml:space="preserve">
    <value>Hello world</value>
  </data>
</root>

^{Listing 18: String resource matches}

The <data> element specifies the name of the variable in its name attribute while the <value> element contains the string translated into a corresponding language.

Note: You can use the Resource File Editor in Visual Studio, which provides you with a more user-friendly way of editing resource file lists.

As it has been mentioned above, each language used on the website should have its own resource file with the same variables as well as strings in proper languages.

Location and Naming of Resource Files

For C1 CMS to find and use the correct resource file for localization, the resource files must be placed in a proper place within the website’s file system on the web server. They should also be properly named.

Each resource file that handles string localization must be placed in the ~/App_GlobalResources folder. The file must follow the schema for .NET resource file. (Please refer to the standard documentation on .NET resource file schema.)

When you create a resource file, you should give it a meaningful name. When you create a resource file for the default language on your website, you should name it as:

[filename].resx

However, when you create a file for any other non-default language, the file name must be the same but you should also insert the culture code between its name and its extension:

[filename].[culturecode].resx

For example, you have English as your default language and Danish as the other, non-default language. You should create resource files for each language as:

• Resource.resx (English)
• Resource.da-dk.resx (Danish)

It is quite reasonable to create the first file for the default language, provide all the entries for localization and then create localized versions of this file by copying and inserting the proper culture code in its filename.

Now that you are done creating localization resources, you should use these resources in your templates in a proper way.

Using Localized Strings from Resource Files in XML Templates

As you learned in the section on the <lang:string> element, you can use the latter to provide language-specific strings or texts in XML templates.

<lang:string key="Resource, Resources.Resource.Name" xmlns:lang="http://www.composite.net/ns/localization/1.0"/>

In its key attribute, you should correctly refer to the variable that represents the string in the XML template.

The reference consists of 4 parts. The first 2 parts are the same in all <lang:string> elements:

• The Resource word followed by a comma and a space
• The Resources word followed by a period

The last 2 parts specify the nameoftheresourcefile and the nameofthevariable:

• The name of the resource file without the extension and the culture code (followed by a period)
• The name of the variable that represents the string to be used in its place.

For example, if you have a variable named Customers:

<root>
  <!-- skipped -->
  <data name="Customers" xml:space="preserve">
    <value>Kunder</value>
  </data>
</root> 

in the resource file for non-default Danish:

~/App_GlobalResources/Templates.da-dk.resx

the reference string in the template must be:

<lang:string key="Resource, Resources.Templates.Customers" xmlns:lang="http://www.composite.net/ns/localization/1.0"/>

where “Templates” is the name of the resource file (without the extension “.resx” and culture code “da-dk”) and “Customers” is the name of the variable to refer to the string by.

This will be correctly rendered as “Kunder” on a web page on the Danish version of the website.

Using Localized Content within the Same Template

In some cases, you might need to keep the content within the same template but target different language versions of the website. It is more than reasonable to take this approach, for example, for images that might differ from language to language.

In this case, you should use the <lang:switch> elements with its sub-elements as described in the section on this element.

Automating Localization of Strings with Front-End Localizer

The use of Composite.Tools.FrontendLocalizer has been depricated.