Internationalization support

By default, the CXP core determines the requested locale from your browser settings. This is done by inspecting the "Accept-Language" header field of the HTTP request. The locale is then used for finding a suitable CXP page to execute for satisfying the request. Assuming the browser requests a URL such as /test.cxp, the CXP core now checks to see if there is a /test.cxp.<locale> file. If this is the case, this locale-specific CXP page is executed. For example, if your browsers default language is "de" and the requesting URL is /test.cxp, then the CXP core tries to execute the /test.cxp.de CXP page. If there is no such locale-specific file, the /test.cxp page is executed instead.

Try it out! Include the following two CXP pages in a web project, request /test.cxp from your browser and change the locale of your browser from "en" to "de" or vice versa. Then request the page again.

<!-- test.cxp.de --> 
<!DOCTYPE html> 
<html> 
<head><title>Unterschiedliche Lokale in CXP</title> 
</head> 
<body> 
<h1>Willkommen</h1> 
</body> 
</html>

<!-- test.cxp --> 
<!DOCTYPE html> 
<html> 
<head><title>Different locale in CXP</title> 
</head> 
<body> 
<h1>Welcome</h1> 
</body> 
</html>

Sometimes it makes no sense to have a separate CXP page for each locale. This is specifically true when creating dynamic content. However, defining locale-specific text directly in your CXP page and writing code for accessing it is as tedious as it is error prone. Instead, the text should better be stored independently from your source code and retrieved dynamically. With CXP, text constants inside the source code can be expressed in a locale agnostic way.

The following CXP page locale-sample.cxp outputs a message in different languages depending on the language selected in the browser. This is achieved by using the L"" locale string delimiter for the language agnostic strings. In other words, in CXP there are two types of string literals: ""/[]/'' which are treated as binary data, and L"" which denote locale string tokens.

<!-- locale-sample.cxp --> 
<!DOCTYPE html> 
<html> 
<head> 
  <title>Internationalization support in CXP</title> 
</head> 
<body> 
<h1>@( L"welcome-today")<small> @(Var2LChar(Date()))</small></h1> 
</body> 
</html>

In this example, a locale string token "welcome-today" is being used. Now, the locale-specific texts must be defined for this token. This is done by adding a sample-locale.cxp.locale file to your project. The locale file is named after the CXP page it is associated with, but has a .locale postfix as part of the filename. The content of the locale-sample.cxp.locale file is shown below. .locale files are XML files which have a <context> root node announcing the supported locale(s). The <context> node can have an unlimited amount of <message> child nodes, each of which needs to have a "token" attribute with the locale string token as the value, and one or more locale attributes defining the locale-specific message text.

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?> 
<context view="locale-sample.cxp" locale="en,de,fr,es"> 
<message token="welcome-today" 
   en   ="Welcome,today's date is" 
   de   ="Willkommen,das heutige Datum ist" 
   fr   ="Bienvenue, la date d'aujourd'hui est" 
   es   ="Bienvenidos, la fecha de hoy es" /> 
</context>

To use locale message strings via message tokens coming from a table or variable you need to use the LocaleMessage( <cToken>, SELF ) helper function within your CXP page. Note that SELF references your CXP page which is required to select the proper locale message dictionary. The following code leads to the identical localized message output and illustrates the usage of LocaleMessage().

@ cToken := "welcome-today" 
<h1>@( L"welcome-today")</h1> 
<h1>@( LocaleMessage( cToken , SELF ))</h1>

Best-practice rules for the different locale concepts are:

If a page primarily consists of static content, consider using locale-specific CXP files.

If your page creates dynamic content, use locale agnostic string literals for non dynamic content.

As outlined previously, the default approach for determining the locale is to analyze the "Accept-Language" HTTP request header. However, this approach leads to a limited usability of your website or application as it forces your users to change browser settings for changing the locale. To avoid this, the CXP core optionally supports managing the locale independently from your browser settings on a user-specific level.

Any CXP application can overwrite the browser settings via the :application object of a CXP page. The following code sets the user locale to English and makes your application locale independent from the user's browser settings. A CXP locale definition takes precedence over the browser's language settings.

<% 
// this will set a user cookie: CxcUserLocale = en 
:application:SetCurrentUserLocale("en") 
%>

However, in some cases you may want to provide the users of your web application with a way for changing the locale. For this, the Xbase++ WebUI for browsers features a "setlocale" command which can be triggered via a page element such as a href. The command is declared via a data-action "setlocale" attribute in your HTML markup. A data-parameter attribute specifies the new locale. Once the corresponding HTML element is activated by the user, your CXP content is automatically reloaded with the new locale-specific settings. The locale-sample.cxp page shown below makes use of this feature. It uses links defined in the page for changing the locale of the application. Simply click on a link to reload the page and display the content in the selected language.

<!-- locale-sample.cxp --> 
<!DOCTYPE html> 
<html> 
<head> 
  <script src="http://cdn.computing-anywhere.net/assets/js/jquery/jquery.min.js"></script> 
  <script src="http://cdn.computing-anywhere.net/assets/js/alaska-software.webui.js"></script> 
  <script src="http://cdn.computing-anywhere.net/assets/js/site.js"></script> 
  <title>Internationalization support in CXP</title> 
</head> 
<body> 

<!-- declarative binding of actions to a HTML element using data-action/data-parameter of WebUI for browsers --> 
<li><a href="" data-action="setlocale" data-parameter="en">English</a></li> 
<li><a href="" data-action="setlocale" data-parameter="de">Deutsch</a></li> 
<li><a href="" data-action="setlocale" data-parameter="fr">French</a></li> 
<li><a href="" data-action="setlocale" data-parameter="es">Spain</a></li> 

<h1>@( L"welcome-today")<small> @(Var2LChar(Date()))</small></h1> 
</body> 
</html>

The CXP page above uses jQuery, the Alaska Software WebUI for browsers (pre-release) as well as a helper script for initializing the WebUI. The files are retrieved from a download location provided by the Amazon content delivery network in your local region. These resources are not a partof the Xbase++ installation.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Internationalization support Foundation