CodeCharge Studio

Internationalization and Localization of Web Applications


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:

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:

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).

Select a Locale

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:

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:

Option Description
File Encoding Global, non-language specific option that specifies the character encoding to be used when saving programming code files, such as .php and .asp.
Default HTML Encoding Global, non-language specific option that specifies the character encoding to be used when creating and saving HTML files. This encoding will be specified in the HTML files in the form of a META tag <meta http-equiv="content-type" ...>. Although an encoding META tag can be removed from the HTML pages, it is recommended that each HTML page contain an encoding META tag, so that it can be edited with external Web editors and uses proper encoding when opening and later saving the file.

This default HTML encoding is inserted as a META tag only into new pages when they are created. You can later change the encoding of individual pages by altering the META tag value. Furthermore, in multi-lingual applications the HTML META tag may be overwritten at run-time by the Output Encoding specific to the active language.

When the encoding is not specified here and not present as META tag within HTML, the files will be saved in the system's default encoding.

Date Display Format Global option that specifies the default date format to be used when displaying dynamic data in date format on all Web pages. You can specify either a non-language specific date format, such as "mm/dd/yyyy", or language specific format such as "ShortDate", which will be replaced at run-time with the format specific to the active language or locale.

Note: The global date display format can be overridden by specifying the date display format for individual controls, such as Textbox or Label, in their properties.

Site Locales The list of languages and countries (locales) available in the project for localization purposes. Each of the locales is associated with additional attributes and text translations that can be edited separately by clicking the "Add", "Edit" and "Translations..." buttons.

The "Set default" button is also provided to specify which language should be used by default when the user or the application at run-time specifies none.

Use Internationalization Features This option enables internationalization features within your application. It allows you to generate and publish an internationalized application that can be localized without using CodeCharge Studio, even if you have setup only one language within CodeCharge Studio, such as English. 

If selected, the following features will be incorporated into your application:

  • The text translations (resources) will be published as standalone files, separate from the application code. Therefore, even if you make your generated application code available for sale without CodeCharge Studio, your clients will be able to edit the text or create new translations by editing the resource files on the sever.
  • Ability to accept locale selection requests (via HTTP, cookie, session variable or URL parameter) and activate the corresponding locale.
  • Pages will be displayed in the output encoding corresponding to the active Locale.

If this option is not selected, the text translations will be included as part of the programming code in common files (Common.asp, Common.php, etc.)


  • This option is selected automatically when you have added more than one language in your CodeCharge Studio project.  
  • This option affects only the generated applications, as internationalization features are always available in CodeCharge Studio’s IDE and do not depend on this option.
  • Pages will be displayed in the output encoding specified via the META tag within the page
Advanced Additional options for advanced users are described below.

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.

Option Description
Query String parameter Parameter name that you'd like to use in the URL to specify the locale or language (neutral locale). For example, when the parameter name is "locale" and the URL contains the string "locale=fr" then the French language will be selected and its corresponding locale activated. Refer to the section on Locale Selection and Fallback Process for more details about language and locale selection.

The locale URL parameter automatically sets the session variable and cookie if you select to use them. This allows you to create a single URL that activates a specific language that is preserved for the duration of the session and/or the cookie.

Session variables Name of the session variables that you'd like to use to specify the locale and language.
Cookie Name of the cookie that you'd like to use to specify the locale, and specify its duration in days.
HTTP Header (Accept-Language) If specified, 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.

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:

Option Description
Language Language associated with a set of translations, characters, and rules for presenting information in a localized format.
Country Country that further defines the locale or region, and is associated with a set of translations (resource file). This is optional and if a country is not specified, the associated resource file will be used as the default for the current language.
Country Formats Country that defines the date, boolean and numeric formatting. This option is needed only as a default when the Country is not specified. If a user selects a language without a country the values can be displayed in these default formats.
Output Encoding Character encoding associated with text translations specific to the selected Language and Country. The Output Encoding overrides the HTML encoding specified via the META tag.
Locale ID String that activates the selected locale (Language and Country) at run-time. The Locale ID cannot be modified.
Formatted data samples Examples of numeric, boolean, and date/time data formatted according to the Country or Country Formats specified above.

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.

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:

Requested Locale Selected Locale
(none) en
en-US en-US
en-UK en
sp-SP sp
fr en
fr-CA en

You can find the list of all country locale codes on the Internet at

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.


On-line, printable versions and updates