Internationalization and Localization of Web Applications

Overview

Many web sites need to be adapted to a local or global audience. This can be accomplished by internationalization and localization of the web site and CodeCharge Studio supports web site internationalization (I18N) and localization (L10N).  Internationalization consists of preparing a web site to display language and country specific (localized) content; localization consists of managing and creating localized data and resources, such as translation strings and formats.  An internationalized web site is not usable unless it is localized to at least one language and country locale.

In summary, both processes consist of:

• Specifying language and country (locale) settings, including formats and output encoding
• Placing translation resource keys on Web pages
• Creating translation resources (translated texts)
• Specifying how users will select their language when viewing the web site

When internationalizing a web site, a language and country are usually used as a combination that is referred to as the region, locale or culture. CodeCharge Studio and this document use the term "locale" for the language and country combination. A country selection is optional. When a country is not specified the locale is considered neutral or can be referred to as just a language. Examples of neutral locales that consist of a language are "French" and "Spanish", while country specific locales might be "French-Canada", "French-France", "Spanish-Mexico", or "Spanish-Spain".

When configuring a neutral locale, CodeCharge Studio requires that you select a country whose formats should be used by default, so that even when the country is unknown the data can still be displayed in some acceptable format, like "yyyy-mm-dd" for dates. It is also a recommended practice to use neutral locales to store common text translations, while adding country specific locales to store additional translation strings that are spelled differently in each country. This way you don't need to duplicate the same translation strings. Your application will automatically select a translation from the neutral locale, such as French, whenever a translation is not found in the currently specified language and country, like French-Canada.

All internationalized web sites created with CodeCharge Studio utilize a set of attributes and resources for each language and country, such as:

• Output Encoding
• Language resource file, containing translated text strings
• Date, boolean and numeric formats

The internationalization features and resources are always available in CodeCharge Studio, even when you create a single-language web site. You can internationalize your web site when using a single language, or you can choose to have certain pages internationalized but not others. The internationalization consists mainly of the developer inserting translation keys during application design and replacing them with translated text by the application at run-time. When creating or changing captions on your web pages you have the choice to type the text directly, or insert a translation resource key that corresponds to a translation string in the language resource file. All CodeCharge Studio builders include the internationalization option, and, when selected, will place on your web page the translation resource keys rather than plain text.

The language you select during installation becomes the language of the CodeCharge Studio IDE.  This is also the default language when you create a new project.  To change the language you are working in, select the CodeCharge Studio button above the ribbon bar, and select the Language option.  Note, when you change languages, you will have to restart your project.  The language you are working with in the IDE has no relationship to the internationalization or localization settings in your project (i.e. you can work in English, but develop websites in Spanish).

CodeCharge Studio is installed with a set of translation files for several languages.   Each file is a database of commonly used strings used within a project (e.g. captions, button text) and the language specific string that goes with each one.  CodeCharge Studio does not translate words automatically from one language to another.  The default translation files are located in the installation folder under "Components\Translations\Site".  In this file are a set of resource keys.  Each key is assigned a text string.  These strings are used by CodeCharge Studio in your web pages (e.g. form titles, button text, etc.).  By changing the default locale in your project settings, you can decide which of these translation files, are used to render your web pages when the page is requested. 

When you create a new project, CodeCharge Studio will copy one of these files, corresponding to your default language, to your project folder (e.g. English - en.txt).  When you add translations strings to your project, your strings and the resource keys are appended to this file.  You can add or remove languages to your project thru your project settings.  To add a language, go into your project settings, select the "Locales & Encodings" option, then "Add..." to add a new site locale.   This will copy and include the translation file (e.g. French - fr.txt) to your project.   The default locale is the language currently in use when you build your page.  You can change the default locale at any time.

Your project can have multiple language translations (translation files).  When you add or modify a translation key, you can select from, or define, the translation in any of the languages that you have added to your project (e.g. English & French).   When your project is published, a copy of your translation files are published with your web pages.  Which translation file is selected when your page is rendered depends on how your web page is requested from the server (Select a Locale).

You should make sure before you publish your project that you have the same set of translations in every language file, unless you want specific translations that are particular to a given locale.  If you don't, your web pages may not be rendered properly when they are requested.  When you add a language to your project, CodeCharge Studio copies the translation file from your installation folder to your project folder.  Any custom translations you have made to other languages in your project are not automatically included in the new language file.  Also, whenever you add a resource key and text to one language file, the entry is not added automatically to the other languages.  If you make an entry in one language file, you should add a similar entry in the other.  For example, let's say you change the caption of your form and add English and French translations.  If you later add Spanish, you will need to manually edit the Spanish translation file and add a new caption for your form so that all the translations are consistent.   Note too, when you run one of the builders and 'internationalized' is selected, the builder may add entries to your translation file automatically, but if you later add a locale to your project, the translation file for that locale will not contain those translations unless you add them.

There are several ways in which text ends up on your web page.  You can add text directly to the page.  The text may be part of a control added by CodeCharge Studio, or it may be part of one or more controls added by one of the builders (Working with Builders).   The forms that are generated by the builders have two types of text; text that is part of the form (e.g. form caption, button text, etc.), and text corresponding to your database items.  For example, when you run the Record Builder, the caption for the record form includes, by default, the text 'Add/Edit'.  This type of text depends on the default language selected and the translation text in the translation file.  The caption for the Record form uses the 'CCS_RecordFormPrefix' key in the translation file.  If your default locale is English, the string added to your web page is from the English translation file.  If your default locale is French, then the text 'Ajouter/Editer' from the French translation file is added to your web page.  Which text appears on the web page, depends on how the web page is requested, as described below.

The other text, such as a field caption, is based on the database items the form is bound to (e.g. the caption for the database field product_name is, by default, "Product Name").   These strings are not based on the translation file, or translated in any way.  The text appears however way the item is defined in the database.

The builders have a 'Internationalized' option (under the 'Connection' settings) that affects how the builder places the text on the page.  If this option is not selected, the text is inserted as described above; some text (e.g. form title) is inserted from the translation file and some text (e.g. field caption) is copied from the database description.  

If the 'Internationalized' option is selected, the builder inserts a resource key in the page instead of text.  What you see in the document page is a resource key  (e.g. {res:product_name}) for every text string inserted by the builder.  The builder automatically adds entries to the translation file for every piece of text that it generates on the web page (i.e. form title, field captions, button text, etc).  These entries are only added to the translation file corresponding to the default locale (e.g. English).  You must add the entries to the other translation files if you want the language translations to be consistent. 

Note, the 'Internationalized' option is automatically selected if your project has more than one language translation file.  You cannot select or unselect the option.

On the web page, you see only the resource keys (e.g. {res:product_name}).  What your users see when the page is displayed is the translated text ("Product Name") from the translation file.   Wherever there is text on your web page, you can substitute a resource key for the text, and define a translation string (Placing translation resource keys on Web).

Selecting the locale determines how text is translated on your web page.  When you publish your project, you can use several methods to specify the locale to be used. The following locale selection methods are available:

• URL parameter
  The locale can be specified by the locale parameter "locale" in the URL, for example, to specify French use "locale=fr". A sample URL may look like: "www.website.com/page1.php?locale=fr".
  The locale URL parameter automatically sets the session variable and cookie, if you select to use them as well. This allows you to create a single URL that activates specific locale that is then preserved for the duration of the session and/or the cookie.
• Session variable
  The locale can be specified by the session variable "locale". For example, setting the session variable's value to "fr" will activate the French locale. The session variable will be set automatically when the locale URL parameter activates a specific locale. The same session variable may also be used to select locale-specific content from the database using session-based WHERE parameter or stored procedure parameter.
• Cookie
  A locale can also be saved in a user cookie so that visitors coming back to a web site can view it in the locale that they last selected.
  If enabled, the cookie will be set automatically when the language URL parameter activates a specific language.
• HTTP Header (Accept-Language)
  This is the default language preference automatically provided by Web browsers. The locale will be selected automatically when your Web application detects an acceptable locale selection in the HTTP header sent to the server by a Web browser. For more information please refer to HTTP Accept-Language.

Note: The variable names that set the active locale can be customized via the Advanced Locale Settings dialog.

User Interface

Creating Locales

You can localize your web site at any time during project creation by adding support for additional languages and/or countries in the "Locales & Encoding" section of the project settings. The process of creating a locale consists of the following steps (which do not need to be performed in the same order):

From the menu select Project -> Settings -> Locales & Encoding

You will be presented with a dialog where you will see the following options:

Advanced Locale Settings - Locale Selection

The advanced locale settings contain additional internationalization options, which allow you to specify how the web application should set the active locale at run-time.

In multiple and conflicting locale selection attributes are specified, the higher positioned attributes will override those positioned below them in the order shown in the above dialog. For example, the URL locale parameter will override the locale specified in the session variable, cookie or HTTP Header.

Specifying Locale Settings

The locale (language and country) settings are specified when adding a new locale or editing an existing one from the Locales and Encoding configuration dialog.

The Add/Edit Language dialog shown allows you to specify the following attributes:

The Edit Locale dialog also contains the [Customize...] button that opens the Customize Formats dialog, allowing you to associate custom formats with the selected locale.

The options available in this dialog are self-explanatory and similar to regional settings in Microsoft Windows. The Code Settings dialog allows you to specify the Locale for ASP, PHP and .NET. This is an advanced feature that can be used to override the formats defined by CodeCharge Studio with formats defined by the .NET, ASP or PHP environments and associated with the specified Locale.

Placing Translation Resources on Web pages

You internationalize a web application by placing translation resource keys throughout the web pages. You can localize the page at the same time by specifying the appropriate translation text for each key. All builders can also place commonly used resource keys if you select the "Internationalized" option when running a builder. To place a translation string on a page in the Design or HTML mode, right-click anywhere on the page and select "Insert translation". To convert existing text to a resource key, highlight the text, right click, and select "Insert translation".

You can also define a translation using the Properties pane.   Wherever you would specify a string, you can substitute a resource string and a translation.   For example, you can define a translation for the 'Default Value' property of a Label.

Creating Translation Resources

Central to localizing a web site is to create text translations for each of the locales or languages that can be selected on the web site. CodeCharge Studio includes a translation editor that can be used to create, edit, import and export locale specific translations. The translation editor can be accessed either from the Project Settings -> Locales & Encodings dialog, or from the Project Explorer -> Resources -> Locales folder by double-clicking on the specific locale name.

The following functionality is available in the translation editor:

Feature/Column	Description
Language (selector)	Locale you want to work with.  (All) will show you all the translations for the locales added to your project.  If you only want selected locales to appear in the editor, select (Multiple...) to access the list of all available locales. You can add several locales by holding the CTRL or SHIFT button.
Not translated	Show only those keys for which translation in not defined.
Look for	Search feature to display only those keys and translations where the specified keyword is found.
Add/Delete	Add or delete a translation resource key and associated translations.
Export/Import	Export or import translated resources to or from a comma-separated CSV file.
Key	The translation resource key that identifies a translation string. A single key is used with multiple translation strings that have the same meaning across multiple locales.
Locale (column)	Displays the locale associated with the translation string.
Text	Translation string that will be used to display information at run-time, in place of the key.

 

Note, some translations, such as Chinese may not appear as displayable text in the editor.  This is because the characters are in Unicode.  To view or edit this text, click on the translation next to the key, and select the ellipsis (...) next to the text.  This will open an editor where you can modify the text in the native characters.

The translation resource files are stored in the project folder in Unicode/UTF-8 files, which are similar to ASCII text but can contain international Unicode characters. They hold key and text string pairs, in the format of: Key=Translation, where 'Key' is the translation resource key and 'Translation' is the translated text associated with the key. Each locale utilizes a different resource file name, in the format Locale.txt, where 'Locale' is the Locale ID, such as en-US (en-US.txt) for English-United States, or just "en" for the English language (neutral locale).

Language Selection and Fallback Process

When you publish a localized application it will display information using the default locale and formats until the application or a user selects a different locale. There are several locale selection methods that can be enabled in your web application. The most basic allows the users to specify their preferred region in their operating system or language in their web browser configuration. For example, on Windows computers users can specify their region in the Regional and Language Options. Internet Explorer users can override those settings by selecting preferred languages in IE: Tools -> Internet Options -> Languages. The web browser will then include the user's region or language preferences in the HTTP headers sent when communicating with a web server to access a web site.  If you do not enable this method or if you do not want to support locales specified by the user's browser, you may allow users to select a locale directly on your web site via a list-box or link/URL added to your web pages. For example, you can add a list box or Link parameter that changes the local setting using an URL parameter, session variable, or cookie.  All available methods of specifying a locale are listed in the Advanced Locale Settings section. CodeCharge Studio includes examples that demonstrate how to implement a list-box with language selection.

In some cases a user's web browser may indicate the preference of a language without specifying the country (a neutral locale); in other cases the selected language or locale may not be supported by your application but can be substituted by another language or locale. Web applications created with CodeCharge Studio handle these situations by utilizing locale defaults activated via the resource fallback process.

Resource Fallback Process

In an internationalized web application you will need to specify the default Site Locale, which is the language and country to be used when the web browser does not provide the language preference or a requested locale is not available. You may also offer neutral translations as a substitute for country specific translations, for example, you may provide generic Spanish text to all users who prefer Spanish-Mexico, Spanish-Spain, or any other flavor of Spanish. The process of selecting the generic language text is automatic as long as you create an equivalent generic locale in CodeCharge Studio. Technically speaking, each locale has a code in the format xx-yy where xx is the neutral locale code and yy is the country code.

The fallback process uses those codes, as follows: When a country (yy) is not specified, or an unknown country (yy) is specified the application automatically selects a translation from the non-country specific, fallback locale code xx. And when the xx country code is not found then the application retrieves text translation from the default locale.

Example:
Given the site locales configured in CodeCharge Studio: English (default), English-US, Spanish; and the corresponding locale codes are: en, en-US, sp. The following table represents the mapping of sample locales requested by users to the corresponding locales available in the application:

You can find the list of all country locale codes on the Internet at http://msdn2.microsoft.com/en-us/library/ms533052.aspx.

The fallback process is employed for each resource that needs to be translated. This offers the powerful benefit of being able to translate only those resources that differ between countries. A locale may not be permanently selected because if one resource key is missing then the translation will be taken from the neutral or default locale, but another resource key can be found in the specified locale and then the specified locale's translation will be used. This allows you to place the majority of text translations into a single neutral locale file like English, while placing only non-shared translations into a separate locale file, like English-UK.

It's important to know that the above fallback process applies independently to text resources and formats; therefore, you can create a locale without any text translations and with formats that are specific to each country. For example, you may create a generic resource with English translations and display dates and numbers in different formats if the selected locale is English-US vs. English-UK.

Keep in mind that each locale, including the neutral ones like English and Spanish, must have some formats associated with them. For that reason, CodeCharge Studio allows you to specify Country-specific Formats when you add a new neutral locale and no country is selected per se.

Glossary

• I18N - An abbreviation for the word internationalization (the letter I, followed by 18 letters, followed by N).
• Internationalization - the process of producing an application that can be localized for a particular country without any changes to the program code. Internationalized applications store their text in external resources.
• L10N - An abbreviation for the word localization (the letter L, followed by ten letters, followed by n).
• Locale - a combination of a language and country, also known as region or culture.
• Localization - the process of converting a program to run in a particular locale or country, so that all text is displayed in the native language, and native conventions are used for formatting.
• Translation resource key - short string used as a key corresponding to the translated text.
• Language resource file - a file containing the pairs of translation resource keys and corresponding translated texts.