ibexa

Path

ez publish / technical manual / 4.5 / features / language switcher


Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

  • 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:

    Origin

    Destination

    Destination URL

    Node

    Translated node

    Translated URL alias

    Node with no available translation [#]_

    Original node

    Translation siteaccess, same URL Alias

    Module

    Module

    The URL is passed through for modules

    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> ] )
    

    Ester Heylen (30/11/2009 10:56 am)

    Geir Arne Waaler (15/12/2010 3:31 pm)

    Ester Heylen, Geir Arne Waaler


    Comments

    There are no comments.