Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Language Support in WebsydianExpress

Overview

WebsydianExpress supports a multi-language environment.

This means that it is possible to generate all pages and all menus in several different languages.

In addition to this, it is also possible to generate different language versions of all dynamically generated texts that are shown to the user.

Base language for sites

The base language is the language that will be used if no other language has been chosen. The language you use as the first language for you menu points etc. is your base language.

This means that you will start with a version of your templates, texts, menus etc. in your base language. These can then be translated to other languages you want to support in your installation.

The translation process may take some time, and in order for you to not end up with half a translated site and half a dead site WebsydianExpress simply uses the base language for the parts of the site that have not been translated yet. This way you will have a fully functional site during your translation process. This also makes it possible to test and work with partially translated sites.

It also means that if you have missed translating e.g. a template, everything will still work. The only effect is that the page generated by this template will be shown in the base language.

Single language environments

Many installations will run as single language sites. To make the administration of these sites more simple, the default behavior if no languages have been created in the language table, is to hide language information for language dependent entities.

So, if the administration interface does not show the language dependent options described below, it is probably because no languages have been created.

When you create a user or a folder in a single language environment, it will just be registered as using the base language of the site.

If you later want to introduce multi languages for the site, the language support will still work - the existing records just belong to the base language.

Language maintenance

You must specify the languages you want to support in your site.

This is done in the administration interface under "Internationalization", "Languages".

Encoding

If all the languages specified for the application use the same encoding, you can disregard the information in this section of the document - just don't specify any encoding for the languages.

The Windows and Windows/iSeries variants do not support multiple encodings. For these variants the encoding will always be determined by the language specified for the server running the application service jobs.

Encoding for each language

If you do not specify any encoding for a language, the pages sent to the user will be in an encoding that is determined by:

For Java and iSeries installations, you can override this for each language by specifying an encoding in the encoding field in the language maintenance.

Doing so means that the runtime will convert all data sent to the browser to the specified encoding.

Encoding for templates

The encoding of the language and the encoding of the template are unrelated. They can be determined independently.

This means that even though you have specified a specific encoding for a language, you do not have to change the encoding of the templates. The runtime reads the template and converts it to the internal encoding of the application service job (based on the encoding used to save the template). When the page is sent to the user, it is converted to the encoding specified for the language chosen for the user.

The  replacement marker /(WSLNGENC) is available in the PageGenerator for you to create a correct content type meta tag. Change the meta tag in the templates to hold the replacement marker for the encoding like this.

 

<meta http-equiv="Content-Type" content="text/html; charset="/(WSLNGENC)">

Translating language information

You may want to show a list of the languages the user can choose to see the site in. The names of the languages in the list must be in the language selected for the session. To provide this possibility, the language information can also be translated.

Use the Translate button on the language grid page in the administration interface for this.

Assigning languages to users

You must assign a language to each user.

There are two ways to do this. You can use the user administration in the administration interface , or if you have created your own functionality for selecting a language for a user, you can use the User.SetLanguageCode API.

When using the administration interface, please note that the drop down box for languages only will be shown if you have created one or more languages for the site.

You can either specify one of the created languages or you can specify *Base or *Site for the user.

If you specify a language, the runtime will search for translations into this language. If no translations are found, the base language will be used.

If you specify *Base, the runtime will not search for any translations. The base language will be used.

If you specify *Site, the runtime will start by using the default language specified in the site settings. This can be either *Base or a specific language. If the default language for the site is changed, the language shown for the user will also be changed.

Languages for anonymous sessions

The language used for sessions where no one is logged in is determined as follows.

In the site settings, user administration, an anonymous user is specified. The language set for this user will be used for anonymous sessions.

Templates (static text)

The HTML-templates used in WebsydianExpress provides the static texts shown to the user.

To provide translations of the site you must create different language versions of all templates, and you must ensure that the runtime finds the template in the correct language when it generates the page.

To ensure this you must create a template folder for each language you want to be able to translate to. In the template folders you place the translated templates for the given language.

Each folder then contains one single language environment. When you build your folder lists, you combine the folders for the languages by adding the language folders to the folder list. 

Dynamic texts

In addition to the templates, which contain the static texts, some texts are generated by the programs when the application is executed. These must also be translated. There are several types of dynamic texts. The translation of each is described below.

Menu item texts and menu link texts

When you define a menu item in the site structure, you specify the text of the menu item when the menu is loaded: "Products", "About us", etc. These texts can also be translated.

The menu item texts are also used as default for menu links. The menu links will also be translated when you translate the menu item texts.

Messages/texts shown on generated pages

In some situations, you want to show a message to a user. A common example is when a user tries to log into the system, but fails to provide a correct user / password combination.

In this case, you would want to show a message telling that the login failed. This text can also be translated.

Message log messages

The messages shown in the message log can also be translated. This means you can let non-English speaking administrators monitor the message log.

Multi-language version of the administration interface

The administration interface comes in US-English only. However, as you can create your own templates, messages etc., you can yourself provide an interface in another language, but as this is comprehensive task, we recommend that you only undertake it if absolutely necessary.

Language support in business processes

You must also ensure that your business processes are provided with the necessary language support.

The language dependent templates can be controlled as described above. Texts for menu items can be translated as described above.

You can create your own text and log messages using the abstract functions Abstract.CreateTextMessage and Abstract.CreateLogMessage from the WSYAPI model - and translate them as described above.

The last thing you need to handle is if any of your entities contains information that must be translated. You must build the necessary functionality for translating the information and for showing the translated texts in your own business processes. WebsydianExpress does not provide patterns for this.

To be able to work with languages in your own business processes, you need to know the language code of the current session.

To find the language code use the abstract functions: ProcessEntryPoint, PageGeneratorForProcess, and EventHandlerForProcess, which contain a field that specifies the current language code.

You can use the following API's to access and change language information:

APIs for working with languages

To create language aware business processes use:

Business process ChangeLanguageForSession

A business process that enable the users to change the language for the session is delivered as part of the runtime.

The implementation of this business process is included in the WSYAPI model. This means that you can inherit from this business process if you want to make your own custom version of it.

Step-by-step guide to introducing languages in a site

This introduces the necessary steps for upgrading a site to a multi-language environment.

Using callback functions to override default behavior

If you want to change the way languages are assigned to a session, there are two relevant callback points you can use.

SessionAfterCreate

This callback point is called just after the session is created. You can use this callback point to control the language for the anonymous sessions.

When a browser sends a request to the application, it contains information about the language it uses. You can retrieve this information and set the language for the session and your site accordingly.

Use the Session.SetLanguageCode API to set the language for the session.

UserAfterLogin

This callback point is called just after a user has logged in. If you do not want to use the language specified for the user, you can use this callback point to control the language for the session.

Use the Session.SetLanguageCode API to set the language for the session.