The dual language product replicates content from one subsite into another, which can then be translated into another language. It aims to produce identical content structures in two websites, with the two variants linked together, which a user can then switch between. It has primarily been developed to be used in the UK to provide English and Welsh versions of the same website.
This documentation refers to "primary" and "secondary" language articles without implying that one language has primacy over the other. Secondary is simply a shorthand way of saying "needing to be translated".
Overview
The multi-language system works on the concept of a "primary" tree of articles and a "secondary" tree of articles in another subsite. The structure of these article trees should be the same. Whenever an article is added/edited/deleted in the primary tree, the secondary tree is also updated by a custom event handler (see below). Updates to the secondary language articles are not passed back to the primary.
For example, if an article is added beneath the "news" section of an English language subsite (which has been set as the primary site), a copy of that article will be made and placed beneath the appropriate article in the Welsh language subsite, ready to be translated.
Approval Requirements should be set up for the whole of the secondary language article tree, preventing untranslated articles from going live. The first stage approvers should be users who will translate the copied article into the relevant language. Subsequent approvers can then be put into the approval chain as normal.
Secondary language articles store the ID of their primary counterpart in their article extras. This ID is added in when articles are replicated. If you are manually creating the content of a brand new site for the first time (home page, search, structural articles like "top utility" etc) you must edit the secondary article tree and populate the extras with the IDs of the primary equivalents.
Article Replication Behaviour
Whenever changes are made to content in iCM, iCM generates gateway messages which can be used to make calls to a custom event handler. The dual language custom event handler is a script that is responsible for maintaining the articles in the secondary language tree.
The script makes use of two users who must be configured in iCM. The first is used for copying articles to the secondary tree. This user must not have the publish-immediate privilege otherwise articles in the secondary tree will go live before the translators have worked on them. The second user is for administrative/housekeeping tasks and for deleting articles. It must have the full set of article privileges.
New Articles
When a new article is published in the primary tree the custom event handler will create a copy of that article in the secondary tree. It will be placed beneath the equivalent parent. If there isn't a suitable parent in the secondary tree then the custom event handler will add a temporary, "display-off", search-disabled placeholder parent first.
In this example "Tim's new article" has been created in the English subsite. A copy has been made into the same location in the Welsh subsite, ready to translated by one of the approvers.
Updating Articles
When an article is edited in the primary tree the behaviour of the custom event handler depends on:
- Whether the update was marked as "significant" in the version control dialog when the change is submitted
- Whether there is already an awaiting approval version of the secondary article
Significant updates are rewrites that need to be translated in their entirety. The content of the primary article is copied to the secondary counterpart, replacing the existing content, and the article enters an awaiting approval state ready to translated. Any existing awaiting approval (or other preview/work in progress) versions of the secondary article are deleted. The existing live article remains in place until the article is retranslated and approved.
"Insignificant" updates are minor changes that don't warrant a full rewrite. The existing secondary article is resubmitted to the approval chain with relevant "notes to approvers", but the existing content is not replaced by the primary version. It's up to the translator to check whether the update in the primary language article needs to be replicated. If a minor change cannot be submitted because the secondary article is already in an approval state then the minor change is queued.
For updates to run smoothly, editors of the primary language articles should make full use of "notes to approvers" and version history notes.
Deleting Articles
When a live article is deleted from the primary tree, the secondary equivalents (both live and preview) are deleted immediately without approval.
Error Handling
It is possible for the custom event handler to fail when secondary equivalent articles are locked. If this happens the first stage approvers for that part of the tree are emailed.
Subsite Settings
The following subsite settings need to be configured in both the primary and secondary subsites. This sets the locale for each site and links them.
Locale
In the Look and Feel section, enter the locale for your site, for example
Dual Language
These settings link the subsites together.
| Setting | Description |
|---|---|
| Enable dual language | Either Yes or No |
| Linked subsite ID | The ID of the subsite providing the alternate language. For example, if subsite 2 was English and subsite 3 was Welsh, the English site would have 3 entered into this box, the Welsh site 2 |
| Override top utilities header | If Yes the site's top utility menu will have a language switching link inserted into it automatically. If No you should create an article using the Language Switch template and place it in your top utility menu yourself |
| Dual language media types | If your media definitions have been set up to provide alternate components for each language set this as Yes. See below for more information |
Language Switcher
These settings control the pop-up dialog when a user first visits a dual language enabled site.
Selecting a language will direct the user to the appropriate site and set a cookie to save their preference. The text of the buttons is not managed via subsite settings but provided by the internationalisation token
| Setting | Description |
|---|---|
| Show pop up | This enables the language switcher dialog. This should generally always be enabled and is based upon the guidance from the Welsh Language Commissioner welsh-language-standards/codes-of-practice (opens new window) "Using a splash welcome screen for the purpose of offering a clear language choice, in order to ensure that the body makes an active offer to users to use the Welsh language before accessing the website's services or self service machine" |
| Heading | Override the default heading text. The headings from both linked subsite are displayed |
| Tagline | Override the default tagline. The taglines from both linked sites are displayed |
Language Cookie
Once a user has chosen a language a cookie is set to save their preference.
| Cookie Name | Example Content | Expires |
|---|---|---|
| languagepref | cy (this is the locale set for the subsite) | One year after being set |
Users
Two iCM users should be set up for the dual language functionality. In a standard installation these are called MULTILANGUAGE-CONTRIBUTOR and MULTILANGUAGE-DELETE.
MULTILANGUAGE-CONTRIBUTOR should have the ability to create all content types in the secondary subsite. It must not have the article publish-immediate privilege.
MULTILANGUAGE-DELETE should have access to all of the same privileges as the contributor, but also have publish-immediate.
The details of these users should be added to the
Full details of these users and the privileges they should be assigned are found in the installation instructions.
Language Switch Template
The Language Switch template displays no content of its own. It has no article extras, no related content and is never viewed directly on your site.
Articles using the template should be placed in relevant places on your site, either in the top or footer menus. When a user follows the link to the article they are instead redirected to the version of the article they were viewing on the alternate language site.
The heading of the article is generated automatically using the internationalisation token
Media Types
Note that this is not a standard feature of iCM and will require an update to your media definitions
Document media types can be managed in two ways.
You could create media items for each language you need to support, for example one media item for a Welsh PDF, one media item for the English version of that PDF.
Alternatively media can be managed using a single media item with multiple language components.
In this example the pdf component provides the English language, the Welsh components provide the file and alternate title and description. The same media item can be related to both the English and Welsh articles, and the site provides the correct component for the correct language.
Installation
The dual language product should already be installed in your iCM by a member of the GOSS team (there's full documentation in GitLab for any GOSS developer reading this).
Share this page
