plone.app.multilingual is used for Plone > 4.1, works with both Archetypes and Dexterity
For many years LinguaPlone has been the most widely used product for maintaining of multilingual Plone websites. But now, when Dexterity content types are built-in for Plone 4.3 and will become default content types in Plone 5, developers need to search for a new solution. plone.app.multilingual (PAM) uses ZCA technologies and enables translation for both Archetypes and Dexterity content types. It provides unified UI for content translation management, although it works only with Plone 4.1 and above. Plone’s interface and main functionality are already translated in more than 60 languages, so there is no need to translate built-in elements. The only thing to translate is content and PAM was built as user-friendly product specifically for this aim.
How to install
NB! Installation instructions may differ depending on plone.app.multilingual version and Plone version, so we recommend to consult product's repository and use the most recent instructions.
plone.app.multilingual consists of four components. The first two are necessary for proper work:
- plone.app.multilingual (UI),
- plone.multilingual (core),
and you can install one of the other two components depending on the content type you would like to use:
- plone.multilingualbehavior (enables Dexterity support via a behavior),
- archetypes.multilingual (enables Archetypes support).
In order to install these packages add the following line to the eggs list in your buildout.cfg file:
eggs =
…
plone.app.multilingual[archetypes, dexterity]
Then re-run your buildout, restart your instance, and activate the newly available add-ons. Language section of the Site setup configuration panel has been modified with extra tabs. To start the translation of your website just choose the desired languages from the Available languages menu. For example, we will add English (as the main language), German and Ukrainian.
After this PAM automatically creates root folders for each of this languages and one for the neutral content. Further content will be divided among one of this folders:
https://yourwebsite/en/
https://yourwebsite/de/
https://yourwebsite/uk/
https://yourwebsite/shared/
If you are using PAM on an existing or a brand new website, it is highly advisable to run the following procedures: go to the Language settings in Site Setup, choose 'Clean site setup' tab and tick both 'Set the default language' and 'Move root content to deafult language folder' boxes.
If you are using Dexterity content types it is important to enable multilingual support for each of them before translating. For this go to Site Setup, choose Dexterity Content Types and select content type you would like to be translatable. Click on the 'Behaviors' tab, tick the box near 'Multilingual Support' option and save new settings. Repeat the same procedure for all content types.
Icons for transition between languages are put automatically in the upper right corner of the window and the one you are viewing at the moment is in bold.
First of all, it is important to manage assets and side resources (e.g. images, video, documents) properly. PAM automatically creates folder Language shared (https://yourwebsite/shared/) that is visible and accessible from all language folders and has ‘neutral’ set as default language. For example, create folder with images with such address https://yourwebsite/shared/images and upload or paste all images there. Start editing the folder and switch to the Settings tab. Tick Exclude from navigation and folder with images will not appear on navigation tab, though you will be always able to insert images from it into any content type of the language folders and if you change original image, it will be changed in all content where it is used.
How to Translate
After adding the first page in one of the languages, appears additional Translate drop-down menu that gives user opportunity to manage translations. 
The first option Edit with babel view enables side-by-side content viewer. On the right side you can see the edited page and on the left side PAM searches for existing translations that are connected with this page. An ajaxified dynamic selector shows translations immediately after clicking on the button.
It would be more comfortable to be able to edit shortnames while translating. To do it, go to Preferences, switch to the Personal Preferences tab, tick the box for Allow editing of Short Names, and click Save.
Always start from the top. Since Plone websites have hierarchical structure it is important to mirror it in the building of language folders. Content is not copied automatically into the another language. If you want to have a page in certain folder in English and German, then you need to create a translation of folder into German and only then create a translation of the page.
E.g.:
Multilingual (folder) -> Multilinguality (page)
Mehrsprachig (folder) -> Mehrsprachigkeit (page)
If you want to create independent content that will be only in one of the languages and will not have translations, you need to go to the language folder and create it directly there. In other cases choose Create… from the Translate drop-down menu and content created in the side-by-side content viewer will be automatically inserted into the chosen language folder.
If translation already exists, you can select Add translations… from the Translate drop-down menu, browse the existing content and connect it as translation. Remember that neither content would change its location during this operation. It just would be viewed by PAM as translation and would be redirected during the language change.
In the same way content can be disconnected as a translation. Click Remove translations… and choose the language, page in which doesn’t correspond to the one you are viewing.
If you mistakenly added page in German to the English root folder, then choose option Set content language from the Translate drop-down menu and choose Deutsch from the Language menu. This content will be moved into the German root folder without the need to do it manually (Cut/Paste functionality).
How to Display Translations
There are situations when there is no corresponding translation in all language contents. Then PAM offers two types of behaviour (go to Site Setup -> Language -> General tab and choose Policies tab):
- search for the closest translation in the parents content chain;
- show user dialog with information about the available translations.
The first one is similar to the LinguaPlone, second option proposes the list of available translations in other languages.
How to View Translation Map
Despite simpleness of PAM usage, the more content you have, the easier it is to get lost on your own website. To avoid confusion PAM introduced tool that displays current translation information. Go to Site Setup -> Language and choose Translation Map tab.
Here you can select language and see its contents tree as well as existing translations of each item. It is easy to control website structure and detect the missing translations of those content types that have to be “mirrored”.
How to Migrate
If you have already translated content, it is easy to set the necessary language or simply move it to the appropriate language root folder. If this content was translated with the help of LinguaPlone, PAM can migrate it. Just got to the Site Setup -> Language and choose Migration tab. Follow simple instructions and your content will be cleanly migrated to the corresponding language root folders.
FAQ’s
Why after using Translate option translated content is saved in the language root folder?
When you use Translate option to translate certain content into another language, you expect it to be ‘mirrored’ into the chosen language website structure. There is a problem if instead your new translated content is saved into the language root folder regardless of the placement of its original. Such issue means that one or several of the previous content levels in the website hierarchy have not been yet translated into the desired language. Thus PAM doesn’t know where to place translated content and saves it into the most obvious place, where you can easily find it.
To avoid such issue please properly mirror the website structure of the translated content.
your-website/en/folder-1/folder-2/folder-3/page-1
your-website/de/ordner-1/ordner-2/ordner-3/seite-1
In conclusion:
- Save all common content in shared folder.
- Always start adding translations from the top.
- Use Translation Map to view current state of website translations.
Don’t forget to use this important tips and make your website multilingual.