Multilingual website

Here it is explained, how to create multilingual websites.

Multilingual website in Allmice CMS is meaning following functionality...
A language chooser block can be added to the website. This language block would include previously configured language links and by clicking one of these language links, the website would change into another corresponding language.

On  this page it is explained, how to add such language chooser block and how to prepare the website in a way, that the language block would change the content into another language.

First of all - Language module should be installed if wishing to make a website to support multilingual functionality.
As in general with a module - there are also explaining guides by every form element of every method of the module.
One way, how you could find links to all of the methods of Language module, is going to [path-to-your-website]/system-manager/manage-access and choosing there module Language. Every row in the table is representing a method of the module and the links are called "Try" in the rows of the table.


How the language will be chosen in the system

The system must know, in which language to display the content, which will be decided in three steps:
1. Main language
Main language can be considered as a not changeable default language. If logging in with a user, who has admin user role and without any other language configuration, the main language will always be chosen. There is a config entry in GlobalCore module, which uri is mainLanguage. Although the value of this config entry can be changed, it is suggested not to change it. Main language is by default English and it is suggested to keep it English. Changing it would make some admin menus not accessable or could cause other unpredicted behaviour in the system.
2. Default language
Default language can be considered as a changeable default language. There is a config entry in GlobalCore module, which uri is defaultLanguage. When the value of this config entry is not empty, then system tries to separate from the value language codes and roles, for which this default language will be used.
For these roles then the default language will be chosen by default (not main language). For role admin still main language will be chosen even if it will be added to default language config entry. In most cases it makes sense to add to the roles anonymous only, because when the visitor lands on the website, then (s)he has anonymous role, when (s)he logs then in, then the default (but also chosen) language will not change.
Caution: If you wish to use as default language something else, than main language English, then be sure, that you have prepared everything for such different language (read below) - especially created needed blocks for the different default language. Otherwise system may not find needed components using different language code and website may not work for the roles, which are related to the default language.
3. Block chooser language
Block chooser language is visitor specific (not role specific) language and is related to visitor's browser's cookie. If it will be chosen by visitor through language chooser block, then it stays active for this visitor until cookie (session) expires. If this visitor logs in as an user, who has admin role, then main language gets active and block chooser language expires.

The content of the website, which is related to languages, can be separated mainly into two groups: Phrases and Relations.
Shortly: phrases are parts of modules or blocks, but relations are meaning language connection between custom items created through modules.


Phrases - translating modules

Phrases are small text fragments which are related to blocks, module form elements and to other such software parts of  the website. E.g. "Log out" link on a user block is a phrase in English and the corresponding phrase in German should be "Abmelden".
Phrases can be changeable (dynamic) or not changeable (static). Dynamic phrases have unique identifiers, which determine, what module, event and other part (e.g. some form element label) they are related to.
Dynamic phrases are good not only for translating the modules into other languages, but also to change the wording of module components in other way if someone  fancies it.

Not all modules and not all module methods are supporting dynamically changeable phrases at the moment because of the limitations of time and financial resources of developing Allmice CMS. It is considered, that the main administrator of the website can understand English good enough and doesn't actually need multilingual functionality for his/her purposes.
The goal has been to provide dynamically changeable phrases for such modules (more precisely for such  methods of various modules), which are usually used also by other users, than the main administrator. E.g. for other editors, creators and readers of web pages add, edit and view methods of Page module have dynamic phrases, most of the User module methods have dynamic phrases, etc.


Relations - translating pages (Page module entries)

Relations are relating together custom content items of different languages, which are created through modules. Current versions of Language module are handling relations as pages only, which are created through Page module, which are in different languages. Future versions of Language module may consider by relations also items created through other modules.

By creating a new page it has no language data related to it and is considered to be in the language, which is currently active (if not using multilingual functionality, then usually the default main language English). To add language information to a page, a relation must be created, which includes data such as language code of a webpage, parent item id (i.e. page id of the version in main language) and child item id (i.e. page id of the current language version). If using multilingual functionality, then every page version in main language should have a relation for itself too.
Let's explain the relations also through the following example...
Imagine that there is a webpage with title Cat in English, which page id is 2. To translate it into German there must be also another page - let it be page with title Katze, which page id is 22. Now for translating (for changing the page, if another language is chosen) there must be 2 relations: 1) language code = "en", parent item id = 2, child item id = 2; 2) language code = "de", parent item id = 2, child item id = 22.


Add language chooser block

Go to [path-to-your-website]/block/add and add the block with following details:
Block code: languageChooser
Block building module: GlobalCore
Type: uriBased
Block building method: setChooserBlock
Region code: languageArea
Access right for roles: admin, anonymous, authenticated
Rank: 1
Path: modules/Language/Model/LanguageBlocks.php
Block status: Active
Language code: en

Before choosing any other language through this block, make sure that there exists language chooser block also for this other language! Add also other blocks for the chosen language (e.g. block for user authentication), which you wish to display using this other language.

Time and date formats for a specific language

Allmice CMS is supporting also changes in time and date formats, if a web site will be shown in a different language.

By using Language module methods add-language-details and edit-language-details specific time and date format can be assigned for every language.
The time and date formats entered in such a way have no effect, if language chooser block is not added and if this block is not active.

If language chooser block is not used, then time and date formats for main and default languages can be changed using config entries in GlobalCore module, which are determined by their unique resource identifiers (uris) mainTimeFormat, mainDateFormat, defaultTimeFormat, defaultDateFormat.


Blocks and translating menus

Simply create a new menu for every different language writing the menu title in the corresponding language.
By creating pages in foreign language, choose the corresponding menu and add item for it in the same language.
By relating a menu to a block make sure, that you choose a block with proper language code.
Blocks include language information and language code can be added by creating a new block or by editing an existing one.
When choosing another language on a website only the blocks will be shown, which correspond to the new chosen language.
Summary of translating menus: Write the new menu and its items and corresponding pages in the translated language. Use for such translated menus a block with translated language code.


To change language in (other than menu) block content, do following...

Make sure, that every block, which is in use in English on the website (if English is main language) has another block version also with another language code. Only block code should be different, other attributes of the blocks in different languages must be the same.
There should also be a distinct language phrase for every language, where phrase text and language code are different, but everything else is same.

For example, imagine that the website title is in English "Pets" and if choosing language German you wish it to be "Haustiere", then make sure, that there are:
1. Two language phrases as follows
1.1. Language code: en
Phrase text: Pets
Type: 11
Module name: GlobalCore
Specific name: siteName
Uri: siteName
1.2. Language code: de
Phrase text: Haustiere
Type: 11
Module name: GlobalCore
Specific name: siteName
Uri: siteName
2. Two blocks as follows
2.1. Block code: siteName
Language code: en
Type: siteName
Building module: GlobalCore
Building method: getSiteName
Region code: siteName
Access right for roles: admin, anonymous, authenticated
Rank: 1
Path:
Block status: Active
2.2. Block code: siteName
Language code: de
Type: siteName
Building module: GlobalCore
Building method: getSiteName
Region code: siteName
Access right for roles: admin, anonymous, authenticated
Rank: 1
Path:
Block status: Active


To change language in menu block content, do following...

Menu blocks are exceptional blocks meaning, that in addition to language code also block code should be different. The reason for such difference - block code in case of menu blocks is an unique  identifier of a distinct menu and two menus in different languages are distinct menus.

For example, imagine that you have made two menus - one in English and the other, which links to translated pages, in German. Links to pages in English are in menu "content" and if choosing language German you wish there to be the translated menu "contentDe". Then there should be two following blocks:
1. Block for the menu in English
Block code *: content
Language code: en
Building module: GlobalCore
Type: Menu
Building method: buildMenuBlock
Region code: menuArea
Path:
2. Block for the menu in German
Block code *: contentDe
Language code: de
Building module: GlobalCore
Type: Menu
Building method: buildMenuBlock
Region code: menuArea
Path: