[[#wd Lookup TitleRecipe23 ]]

Overview

COAST supports two mechanisms for localization:

  1. Localization of individual strings may be achieved by using a StringRenderer. By localizing individual strings StringRenderer offers a very fine level of granularity. The approach is generally taken if there is not too much text to be localized and the overall layout of the page stays the same no matter what the current language might be. (Examples of short strings that might be localized this way might be titles, labels, headings, etc.)

  2. Whole Pages may be rendered language specific by using different HTML templates with the HTMLTemplateRenderer. This approach offers a more coarse level of granularity. It is usually used were the structure of a page depends very much on the chosen language. In those cases there is generally not enough common page structure that might be shared among different localized pages.

There are several language related settings in the Config.any configuration file. These define if and what localized versions are supported by the COAST server.

Preconditions

It is assumed that the un-localized application already exists, i.e. all the necessary configuration files for roles, pages etc. are completed.

Steps to do:

  1. The first step to get language specific pages is to setup the localization related entries (Language, UseBrowserLang and LanguageKeyMap) in Config.any.
    Example: Localization related settings in Config.any:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"# set the default language to "E" (English)"
    		"/Language		E"
    		" "
    		"# enable the language settings of the clients browser"
    		"/UseBrowserLang	1"
    		" "
    		"# mapping of browser settings to abbreviations of the supported languages"
    		"# this server supports four languages: D, E, F, I (e.g. German, English, "
    		"# French and Italien)"
    		"/LanguageKeyMap {"
    		"	/D	{ "de" "de-CH" "de-DE" "de-AU" }"
    		"	/E	{ "en" "en-GB" "en-US" }"
    		"	/F	{ "fr" "fr-BE" "fr-CA" "fr-FR" "fr-CH" }"
    		"	/I	{ "it" }"
    		"}"
    	}
    }]]
    
    Notice: In COAST a language is typically identified by a short string. (In the above example the strings "D", "E", "F" and "I" were used as identifiers for German, English, French and Italian.) This identifier is used by COAST to retrieve localized versions of strings and HTML templates.

    All the localization related settings in Config.any are optional:


    Example:
    In the above example the default language was set to "E" (English). Evaluation of browser settings was enabled and a map for various browser settings was defined. (If a user has defined French to be the language of his choice, each of his requests will contain the browser setting "fr". Because of above 'LanguageKeyMap' each such request will cause COAST to use its "F" localized version.

  2. Localizing strings:

    A given string may be localized by replacing the respective text with a call to a StringRenderer. (This indirection allows COAST to render a language specific string.)
    Example: The static text "Good day" is replaced by a call to a StringRenderer:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"<td>Good day</td>"
    		" "
    		"becomes:"
    		" "
    		"  <td>[[#wd Lookup myString ]]</td>"
    	}
    }]]
    
    All that remains to be done is to define a respective renderer specification for 'myString':
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/myString {"
    		"	/String {"
    		"		/F          "Bonjour""
    		"		/E          "Good day""
    		"		/CH         "Grüezi""
    		"		/Default    "Guten Tag""
    		"	}"
    		"}"
    	}
    }]]
    
    (Notice: The slot names for the different localized versions of a text directly correspond to the language identifier used by COAST. If the StringRenderer specification does not contain an entry for the current language identifier then the 'Default' entry is used. A minimal specification for a String Renderer must always contain the 'Type' and the 'Default' slot.)

    Although the renderer specification of an individual StringRenderer may be placed in any configuration file, it is usually put in a separate file. (So as to collect all translated strings in one place.) In Config.any the entry 'StringFile' may name a file where you want to keep your localized strings:
    Example:

    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/StringFile		"MyLocalizedStrings""
    	}
    }]]
    
    You might now put the Renderer specification for 'myString' in the file 'MyLocalizedStrings.any':
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"# content of: MyLocalizedStrings.any"
    		"{"
    		"	/myString {"
    		"		/String {"
    		"			/F          "Bonjour""
    		"			/E          "Good day""
    		"			/CH         "Grüezi""
    		"			/Default    "Guten Tag""
    		"		}"
    		"	}"
    		"}"
    	}
    }]]
    
  3. Localizing HTML template files:

    The same language identifiers that are used to localize individual strings may also be used to localize whole HTML templates.
    Usually HTML templates are retrieved using the path defined by the Config.any entry 'TemplateDir' below 'HTMLTemplateConfig'.
    Example: All HTML templates are retrieved from config/HTMLTemplates:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/HTMLTemplateConfig {"
    		"	/TemplateDir	"config/HTMLTemplates""
    		"}"
    	}
    }]]
    
    It is now possible to setup different sub-directories for localized versions of individual HTML templates. All the template files for one language go into one directory.

    To setup the different sub-directories add the 'LanguageDirMap' entry to Config.any below 'HTMLTemplateConfig'. The entry defines the mapping from different language identifiers to respective sub-directories in the 'TemplateDir'.
    Example:

    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/HTMLTemplateConfig {"
    		"	/LanguageDirMap {	# maps language key to localized template dir"
    		"		/D				"German_Templates""
    		"		/E				"English_Templates""
    		"		/F				"French_Templates""
    		"		/I				"Italian_Templates""
    		"	}"
    		"}"
    	}
    }]]
    
    The respective directory structure for the configuration files looks like this:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"config/"
    		"	HTMLTemplates/"
    		"		German_Templates/"
    		"		English_Templates/"
    		"		French_Templates/"
    		"		Italian_Templates/"
    	}
    }]]
    
    Usually all default HTML templates are placed in the main 'TemplateDir'. Files in the main 'TemplateDir' may be overridden for an individual language by placing a file with the same name in the respective localized sub-directory. (Notice: Not all HTML templates need to be localized: If no localized version exists, the default version from the main TemplateDir is always used.)

    Example: Page 'MyPage' is using the HTML template 'MyTemplate.html'. Due to a different screen layout special versions of 'MyTemplate.html' need to be used for the german and the english Version of 'MyPage'. All other languages are to use the default version of the file.

    The directory structure for this application might look like this:

    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"config/"
    		"	MyPage.any"
    		"	HTMLTemplates/"
    		"		MyTemplate.html"
    		"		German_Templates/"
    		"			MyTemplate.html"
    		"		English_Templates/"
    		"			MyTemplate.html"
    		"		French_Templates/"
    		"		Italian_Templates/"
    	}
    }]]
    

Remarks

This recipe has not been implemented in the example application.

Glossary

Related Topics

StringRenderer, Renderer specifications, Settings in Config.any