CodeCharge StudioMany 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 technically 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. Technically, 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.
Keep in mind that CodeCharge Studio provides a default language resource file for several languages, which can be used at design-time and/or run-time. When you create a new project, it will contain the default translations file copied from CodeCharge Studio's "Components\Translations\Site" folder. That file contains commonly used text strings, such as "Search", "Login", "Cannot find specified record", etc.
The builders include the "Internationalized" option which, if not selected, will cause the builder to place fully translated text on your web page at design-time. If you select the "[x] Internationalized" option in a builder then the builder will place the translation (resource) key on your web page that will be replaced with the translated text at run-time.
Certain text strings are always stored in the resource file as they contain confirmation and validation messages, such as "The value is not valid", which will be shown at run-time when users enter an invalid field value. Since translation resources are used at run-time, the resource file(s) are published to the web server together with the web application. The translation resources can be published as separate resources, or included in the common code files, depending on your choice to have your published web application internationalized or not.
When an internationalized web application is run on the server, you can use several methods to specify the language to be used by the web page. The following language selection methods are available:
Note: The variable names that set the active language can be customized via the Advanced language settings dialog.
You can localize your web site at any time during the 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:
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.) Notes:
|
| Advanced | Additional options for advanced users our described below. |
The advanced language settings contain additional internationalization options, which allow you to specify how the web application should set the active language 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 "lang" and the URL contains the string "lang=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 variable | Name of the session variable that you'd like to use to specify the locale. |
| 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 language selection in the HTTP header sent to the server by a Web browser. For more information please refer to HTTP Accept-Language. |
In case multiple, 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 language parameter will override the language specified in the session variable, cookie or HTTP Header.
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. |
| Language ID | String that activates the selected Language and Country at run-time. The Language 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 Language 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.
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".
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, and import and export locale specific translations. The translation editor can be accessed either from the Project Settings -> Language & Encoding dialog, or from the Project Explorer -> Resources -> Languages folder by double-clicking on the specific language name.
The following functionality is available in the translation editor:
| Feature/Column | Description |
|---|---|
| Language (selector) | Locale you want to work with. Select (Multiple...) to access the list of all available locales. You can select 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 languages. |
| 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. |
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).
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. In addition to this method, or if you do not enable this method or if you do not 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. 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.
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 are: 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 http://msdn2.microsoft.com/en-us/library/ms145903.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 language 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.