eZ Platform offers the ability of creating different language versions o= f all content in the repository.
The system allows for multiple language versions (translations) of a Con= tent item to be created. Translations are created per version of the item, = so each version of the content can have a different set of translations.
At minimum, a version always has one translation which by default is the= initial/main translation. Further versions can be added, but only= for languages that have previously been added to the global translation list, that is a list of all = languages available in the system. The maximum number of languages in the s= ystem is 64.
Different translations of the same Content item can be edited separately= . This means that different users can work on translations into different l= anguages at the same time.
Language versions actually concern translating values of the Fields of a= Content item. Every Field in its definition in a Content Type can be set t= o be Translatable or not.
Translating the Field values is natural in some cases, for example for t= he body of an article. However, there are Fields where translating is impra= ctical, for instance images without text, numbers, e-mail addresses and so = on. Platform still gives the possibility to mark all Fields as translatable= regardless of their Field Type. It is only the user's (content manager's) = decision to exclude the translation possibility for those Fields where it m= akes no sense.
When a Field is not flagged as Translatable, its value will be copied fr= om the initial/main translation when a new language version is created. Thi= s copied value cannot be modified. When a Field is Translatable, its value = in a new language version will have to be entered by the user.
For example, let's say that you need to store information about marathon= contestants and their results. You build a "contestant" Content Type using= the following Fields: name, photo, age, nationality, time reached. Allowin= g the translation of anything else than nationality would be pointless, sin= ce the values stored by the other Fields are the same regardless of the lan= guage used to describe the runner. In other words, the name, photo, age and= time reached would be the same in, for example, both English and Norwegian= .
It is possible to control whether a User or User group is able to transl= ate content or not. This can be done by adding a Language limitation to Pol= icies that allow creating or editing content. This limitation lets you defi= ne which Role can work with which languages in the system. (For more inform= ation of the permissions system, see Permissions.)
In addition, it is also possible to control access to the global transla= tion list by using the Content/Translations Policy. This makes it possible = to allow users other than the site administrator to add and remove translat= ions that can be used.
The multilanguage system operates based on a global translation list tha= t contains all languages available in the installation. Languages can be ad= ded to this list from the Admin Panel in the user interface. The ne= w language must then be added to the SiteAccess configuration= . Once this is done, any user with proper permissions can create Content it= em versions in these languages in the user interface.
Once more than one language is defined in the global translation list an= d there is content in different languages, the question is how can this be = exposed to use by the visitor. There are two ways to do this:
LanguageLimitation allows you to limit users' editing rights depend= ing on the language of the Content item. See Permis= sions and List = of Limitations for more information.
One of the basic ways of using multiple languages is setting up a separa= te siteaccess for each language.
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 for ex=
ample the case when you use separate siteaccesses for mobile versions of a =
website.
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:
When setting up siteaccesses with different language versions, you can s= pecify a list of preset languages for each siteaccess. When this siteaccess= is used, the system will go through this list. If a Content item is unavai= lable in the first (prioritized) language, it will attempt to use the next = language in the list, and so on. Thanks to this you can have a fallback in = case of a lacking translation.
You can also assign a Default content availability flag to Content Types= (available in the Admin Panel). When this flag is assigned, Content items = of this type will be available even when they do not have a language versio= n in any of the languages configured for the current siteaccess.
Note that if a language is not provided in the list of prioritized langu= ages and it is not the Content item's first language, the URL alias for thi= s content in this language will not be generated.
This is different than in legacy, where this behavior was covered by a g=
lobal control switch ShowUntranslatedObjec=
ts.
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 feature =
to generate links to the Content item's translation, and on
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>
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
ez_trans_prop=
Twig helperez_trans_prop() is a generic, low level Twig helper which c=
orrects the translated value of a multi valued(translations) property.
See ez_trans_prop refer= ence for more information.
V1.8=
Since eZ Platform 1.7.0, the interface has been fully translatable. Vers= ion 1.8.0 introduces official support for Crowdin as a translation managem= ent system. In addition, it integrates support for in-context translation, = a feature that allows you to translate strings from the interface, in c= ontext.
To start translating, you need to set a browser cookie. There are severa= l ways to do this, but we will highlight a couple here.
One way is to open the development console and run these lines:
document.cookie=3D'ez_in_context_translation=3D1;path=3D/;'; locat= ion.reload();=20
document.cookie=3D'ez_in_context_translation=3D;expires=3DMon, 05 = Jul 2000 00:00:00 GMT;path=3D/;'; location.reload();=20
You can easily create two bookmarks to toggle in-context on/off.
Righ=
t-click your browser's bookmark bar, and create a new one, with the followi=
ng label and link:
javascript:(function() {document.cookie=3D'ez_in_context_translation=
=3D1;path=3D/;'; location.reload();})()=20
javascript:(function()=20
{document.cookie=3D'ez_in_context_translation=3D;expires=3DMon, 05 Jul 2000=
=20
00:00:00 GMT;path=3D/;'; location.reload();})()=20
Then click on the bookmarks from platform UI to enable/disable in-co=
ntext.
The first time you enable in-context, if you're not logged into Crowdin,=
it will ask you to log in or register an account. Once done, it will ask y=
ou which language you want to translate to, from the list of languages conf=
igured in Crowdin.
Choose your language, and you can start translati=
ng right away. Translatable strings in the interface will be outlined in re=
d (untranslated), blue (translated) or green (approved). When moving over t=
hem, an edit button will show up on the top left corner of the outline. Cli=
ck on it, and edit the string in the window that shows up.
Make sure you clear your browser's cache in addition to eZ Platform's. S= ome of the translation resources use aggressive HTTP cache.
More info...