Language switcher

Since eZ Publish 4.1, there is a new way to create links that take the users to an other traslation siteaccess. This had previously been problematic, when the URL was not available in the selected translation, because of differences in translation.

The URLs used with the language switcher have the following form:

/switchlanguage/to/<destinationTranslationSiteaccess>/<nodeID|URLalias>

This feature will most often be used via the bundled module switch language. This is an optimized way to translate node IDs and URL aliases into the destination language, for it is done before someone clicks on a language switcher link. This is something which has to be calculated per URL otherwise.

Operation

When a user clicks on a language switcher URL, the user is redirected to an URL, representing the destination siteaccess and the destination content. More often than not the destination content is the translated content originally being viewed, but there are some exceptions to how this works. Here is how:

Note: [#] Nodes can still be viewable in the other siteaccess. For instance, English content can be viewable in the Norwegian siteaccess if English is in the prioritised languages.

Use

Using the language switcher tool, is simply a matter of creating links in the pattern shown above. The links are easy to create with the template language, but there is also another convenience method for creating language switcher URLs (for which you should only need a minimal amount of logic in the templates). You can access this feature via the template operator, language_switcher(). See the next section how to configure this operator.

The operator will return an array, indexed by siteaccess name, containing a language switcher URL and a human readable text.

{def $translations = language_switcher( $module_result.content_info.node_id )}
{foreach $translations as $siteaccessName => $lang}
{*
Note we are not using the $siteaccessName index here, but useful
for matching against current siteaccess for instance
*}
<a href={$lang.url|ezurl}>{$lang.text|wash}</a>
{/foreach}

The input to "language_switcher( $var )" can either be the node ID, the current URL alias or in the case of a module, just the requested URL.

 Configuration

In order to make the language switcher easy to use within templates, some configuration must be done via settings. This is one of the most convenient places to define the translation siteaccess on the site, and this will allow the “language_swither()” operator to not use normal siteaccesses when creating the links automatically.

Below is an example of what a setup can look like:

site.ini
 
[RegionalSettings]
 
# Example mapping between translation siteaccesses and the name to use for the
# language switcher link, e.g. the name which will be used when making links to
# these siteaccesses.
# Example: TranslationSA[<name of siteaccess>]=<name of language switcher link, pointing to this siteaccess>
TranslationSA[]
TranslationSA[eng]=English
TranslationSA[nor]=Norwegian
TranslationSA[fre]=French

Override possibility

Each site has a unique set of requirements, that is why the language switcher class can be fully overridden with a custom class.

The class is configured at site.ini:

site.ini
 
[RegionalSettings]
 
LanguageSwitcherClass=ezpLanguageSwitcher

The implementation class needs to implement the ezpLanguageSwitcherCapable interface.

Extra

The language switcher feature provides one more convenience for template developers, namely the ability to fetch the URL alias of a node in a user-selected translation. This is achieved through the following template fetch function:

{def $demo = fetch( 'switchlanguage', 'url_alias', hash( 'path', $node.url_alias, 'locale', 'nor-NO' ) )}

The above example will give the URL alias for the Norwegian translation, if the URL alias cannot be fetched, or does not exist for the given translation "false" is returned.

The full list of parameters are:

fetch( 'switchlanguage', 'url_alias', hash( [ 'node_id', <node_id>, ]
                                                               [ 'path', <node_path> ] )