A Content item can be translated into several languages. Those lan= guages are configured in the system and exposed in siteaccesses via a prior= itized list of languages:
ezpublish
system:
eng:
languages: [eng-GB]
# In fre siteaccess, fre-FR is always preferred, and fallback to en=
g-GB if needed.
fre:
languages: [fre-FR, eng-GB]=20
When visiting a Content item, it may be useful to let the us= er switch from one translation to another, more appropriate to them. This i= s precisely the goal of the language switcher.
The language switcher relies on the Cross-SiteAccess linking feat=
ure to generate links to the Content item's translation, and=
on RouteReference =
feature.
Tip
If you install the DemoBundle with at least 2 differen= t languages, you will be able to see the Language Switcher and to test it.<= /span>
Configuration is not mandatory, but can help to = distinguish which siteaccesses can be considered translatio= n siteaccesses.
ezpublish:
siteaccess:
default_siteaccess: eng
list:
- ezdemo_site
- eng
- fre
- ezdemo_site_admin
groups:
ezdemo_frontend_group:
- ezdemo_site
- eng
- fre
# ...
system:
# Specifying which SiteAccesses are used for translation
ezdemo_frontend_group:
translation_siteaccesses: [fre, eng]
eng:
languages: [eng-GB]
fre:
languages: [fre-FR, eng-GB]
ezdemo_site:
languages: [eng-GB]=20
Note: Top prioritized language is always used for as th=
e siteaccess language reference (e.g. fre-FR for&nbs=
p;fre siteaccess in the example above).
If several translation siteaccesses share the same language reference,&n= bsp;the first declared siteaccess always wins.
There are some cases where your siteaccesses share settings (repository,=
content settings, etc.), but you don't want all of them to share the same&=
nbsp;translation_siteaccesses setting. This can be the ca=
se when you use siteaccesses for mobile.
Solution is as easy as defining new groups:
ezpublish:
siteaccess:
default_siteaccess: eng
list:
- ezdemo_site
- eng
- fre
- mobile_eng
- mobile_fre
- ezdemo_site_admin
groups:
# This group can be used for common front settings
ezdemo_common_group:
- ezdemo_site
- eng
- fre
- mobile_eng
- mobile_fre
ezdemo_frontend_group:
- ezdemo_site
- eng
- fre
ezdemo_mobile_group
- mobile_eng
- mobile_fre
# ...
system:
# Translation SiteAccesses for regular frontend
ezdemo_frontend_group:
translation_siteaccesses: [fre, eng]
# Translation SiteAccesses for mobile frontend
ezdemo_mobile_group:
translation_siteaccesses: [mobile_fre, mobile_eng]
eng:
languages: [eng-GB]
fre:
languages: [fre-FR, eng-GB]
ezdemo_site:
languages: [eng-GB]
mobile_eng:
languages: [eng-GB]
mobile_fre:
languages: [fre-FR, eng-GB]=20
If translation_siteaccesses setting is not provid=
ed, implicit related siteaccesses will be used instead. =
Siteaccesses are considered related if they share:
To generate a language switch link, you need to generate the =
RouteReference, with the langua=
ge parameter. This can easily be done with
{# Given that "location" variable is a valid Location object #}
<a href=3D"{{ url( ez_route( location, {"language": "fre-FR"} ) ) }}">=
;{{ ez_content_name( content ) }}</a>
{# Generating a link to a declared route instead of Location #}
<a href=3D"{{ url( ez_route( 'my_route', {"language": "fre-FR"} ) ) }}"&=
gt;My link</a>=20
You can also omit the route, in this case, the current route= will be used (i.e. switch the current page):
{# Using Twig named parameters #}
<a href=3D"{{ url( ez_route( params=3D{"language": "fre-FR"} ) ) }}">=
My link</a>
{# Identical to the following, using ordered parameters #}
<a href=3D"{{ url( ez_route( null, {"language": "fre-FR"} ) ) }}">My =
link</a>=20
When using sub-requests, you lose the context of the master request (e.g= . current route, current location, etc.). This is because sub-requests can = be displayed separately, with ESI or Hinclude.
If you want to render language switch links in a sub-request with a corr=
ect RouteReference, you must pass it as an argument to yo=
ur sub-controller from the master request.
{# Render the language switch links in a sub-controller #}
{{ render( controller( 'AcmeTestBundle:Default:languages', {'routeRef': ez_=
route()} ) ) }}=20
namespace Acme\TestBundle\Controller;
use eZ\Bundle\EzPublishCoreBundle\Controller;
use eZ\Publish\Core\MVC\Symfony\Routing\RouteReference;
class DefaultController extends Controller
{
public function languagesAction( RouteReference $routeRef )
{
return $this->render( 'AcmeTestBundle:Default:languages.html.twi=
g', array( 'routeRef' =3D> $routeRef ) );
}
}=20
{# languages.html.twig #}
{# Looping over all available languages to display the links #}
{% for lang in ezpublish.availableLanguages %}
{# This time, we alter the "siteaccess" parameter directly. #}
{# We get the right siteaccess with the help of ezpublish.translationSi=
teAccess() helper #}
{% do routeRef.set( "siteaccess", ezpublish.translationSiteAccess( lang=
) ) %}
<a href=3D"{{ url( routeRef ) }}">{{ lang }}</a><br />=
;
{% endfor %}=20
ezpublish.translationSiteAccess( language ) returns t=
he siteaccess name for provided language (or null if=
it cannot be found)ezpublish.availableLanguages() returns the list of av=
ailable languages.You can easily generate language switch links from PHP too, with t=
he RouteReferenceGenerator service:
// Assuming we're in a controller /** @var \eZ\Publish\Core\MVC\Symfony\Routing\Generator\RouteReferenceGener= atorInterface $routeRefGenerator */ $routeRefGenerator =3D $this->get( 'ezpublish.route_reference.generator'= ); $routeRef =3D $routeRefGenerator->generate( $location, array( 'language'= =3D> 'fre-FR' ) ); $link =3D $this->generateUrl( $routeRef );=20
You can also retrieve all available languages with the =
TranslationHelper:
/** @var \eZ\Publish\Core\Helper\TranslationHelper $translationHelp= er */ $translationHelper =3D $this->get( 'ezpublish.translation_helper' ); $availableLanguages =3D $translationHelper->getAvailableLanguages();=20