Composr Tutorial: Translating Composr content

Written by Chris Graham (ocProducts)
Composr can have its content translated and delivered for each language, without requiring any duplication. i.e. it can be fully multilingual.

This is a very advanced feature that only a very small proportion of users will want. It is intended for large websites produced by tightly-managed sites that have an active team of human translators.
You may want to consult with a programmer to enable the functionality.

Table of contents

  1. Composr Tutorial: Translating Composr content
    1. Pros and Cons
    2. Commandr command
    3. Language choice for CMS actions
    4. Content translation
    5. Allowing guests to choose language
    6. Limitations
    7. Language string references into Comcode fields (advanced)
    8. See also

Composr's multi-language support is available when all the following conditions are met:
  1. you have more than one language installed
  2. you have the Conversr "Enable regionalisation" option enabled
  3. you either installed initially with multi-language support on, or you have run the Commandr command to enable it

Pros and Cons

Pros:
  • Support your content in multiple languages from a single website and content repository

Cons:
  • Requires active translator(s)
  • Makes development more complex, the translate table must be used for all content strings
  • Makes hand-editing the database much harder
  • May slow website searching
  • All sites on a Composr multi-site-network must have the same multi-lang-content status (i.e. all have it, or all not have it).

In short: Use it if you need it, and prepare for the extra cost and complexity. It's an ideal feature for those that need it.

Commandr command

A special Commandr command is required to set up the database structure.
The Commandr command may take some time to run. It is advised you therefore run the SSH version of Commandr, rather than the webapp (slow webapp requests may stall or be cancelled via various levels of timeout).
Log into SSH on your server (or equivalent process to receive a command prompt) and type:

Code (Bash)

php data/commandr.php
 
(this assumes you run it from the Composr base directory, and that the php command is in your path)

Then the Commandr command required is:

Code

:require_code('database_multi_lang_conv'); enable_content_translation();

Depending on the size of your database, the command could take hours to run. You can monitor it progress through tables via MySQL (SHOW FULL PROCESSLIST).

Language choice for CMS actions

To understand what the content translation can do, and how it works, we need to consider the following cases:
  1. Sending newsletters
  2. Editing theme images
  3. Editing Comcode pages
  4. Using the Zone Editor
  5. Content translation (described in the next section)

For '1' (newsletters), you will get a choice what language to send it for when you go to the newsletter module. Subscribers choose their language when they sign up.

Similarly, for '2'-'4', you will get a choice of language which to edit under when you go to the respective section of Composr. What you save will be saved accordingly.

You will notice when you choose your language you will temporarily see the website displayed as the language you are working under, until you finish.
E.g. if you are viewing the website in English, and you go to edit a Comcode page and select to edit to in French, the website will be shown in French while you are editing that page.

Content translation

Image

Content translation

Content translation

(Click to enlarge)

Content added to Composr is initially saved against the language being used by the submitter. Therefore, when adding content you must ensure you have the correct language choice for what you want the default content language to be; a good rule of thumb to check this is by seeing if the language Composr is uses in its interface matches the language you expect to be submitting content in.

For example, if you are adding an article in French, make sure you have your current language set to French by checking the Composr site is being shown in French while you are adding that article.

When editing content, the content is always saved against the language you see it in when you are editing – if it has been translated already then the edit will be saved to your selected language, but otherwise it will stay in the original submitted language when saved (i.e. saving will not save it as a translation for the language you are viewing). Never translate from an edit screen: if something is edited (so long as there were actual changes), all translations are automatically marked 'broken', and will be put back into the translation queue (because Composr doesn't know you haven't made other changes beyond just translating).

For example:
  • if you are editing an article originally added in French, and you are viewing the website in French, it will be edited in French.
  • if you are editing an article originally added in French that has not yet been translated to German, and you are viewing the website in German, it will be edited in French.
  • if you are editing an article originally added in French that has already been translated to German, and you are viewing the website in German, it will be edited in German, but the French version (and any other's apart from German) will be marked "broken".

Content translation is primarily performed in a special 'Translate content' part of the Admin Zone (Admin Zone > Style > Translate website content).

You will see there is also an option in the footer for opening up a 'Translate content' screen just with language strings (the user content kind) that were included on the page you are viewing. This is a nice feature if the main translation queue is to full to realistically deal with and you just want new content to get translated.

In Composr almost everything (*) can be translated, but obviously you would not want to translate every forum post for a large community (for example). For this reason, Composr saves language with 'priorities', and that of the highest priority will be presented for translation first. For example, the names of zones would be the highest priority, while forum posts would be the lowest.

(*) A few things cannot be translated such as forum names. The reasoning is that you do not want such things translated, but rather you should have a different copy of each forum for each language. This is an exceptional situation, and is only designed like this due to the way forums are used. Other kinds of category may be translated as described above.

Allowing guests to choose language

Image

The side_language block

The <kbd>side_language</kbd> block

(Click to enlarge)

You will want a way to be able to give your site visitors the option to view your website in their choice of language. You can easily achieve this by adding a ready made block on one of the side panels (assuming your web designer has not done this already). The code for this is:

Code

[block]side_language[/block]
Any content which has not been translated yet will display in the original language it was written in. For example, a news post will display in English if that's how it was originally written.

Limitations

Content translation may not be supported in every feature perfectly, here are some known limitations:
  • Content CSV import and export is not translation-aware
    • see the next section for a workaround
  • Content sorting will only sort consistently if translations are complete
    • for example, if you have some translations into German, but some falling back to English, and viewing in German, only the German entries will be sorted correctly
    • tracker issue: https://compo.sr/tracker/view.php?id=3732
    • a workaround is the hidden force_memory_sort__<catalogue-name> option, but this has a performance hit

Language string references into Comcode fields (advanced)

If you want to avoid the normal translation interface, you can sometimes use references to your own language strings for the content you add.
For example, for a catalogue have Comcode-supporting field types and put in language string Tempcode-syntax like {!EXAMPLE}.

Advantages:
  • Easier to maintain if you prefer working with code than the translation interface
  • Avoid re-translating if you already have created language strings for the same text
  • Can survive CSV import and export

See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.