HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Tutorial: Translating ocPortal

Written by Steve Jarvis, ocProducts
This tutorial covers how to translate your (ocPortal-powered) website into different languages. It is designed for the more casual webmaster who is not seeking to create a complete ocPortal translation. We also have a more thorough tutorial.

We will show you how to add a second language or even multiple languages onto your website. There are three main stages included within this guide. These are:
  1. Using Launchpad
  2. Translating the Software
  3. Translating the website content
While the first two are both linked together they are both equally important when internationalising your website.



Coding within the language

(This section will make more sense once you've read the rest of this guide)

In many cases there will be some coding symbols within a specific language string. These may be something like '{1}', '{2}', '<tag>', '[block="something"]side_stored_menu[/block]' and so on. It is very important that these are left in the translated text. Whilst you wouldn't translate the word "block", you may want to translate some of the text appearing after a "=" sign, since these may be used for text such as titles. For example, in the following code you would only translate the words 'block title' which are between the "" marks: [block title="block title"]side_stored_menu[/block]. The rest of the text would need to be left or else the software would not understand it any longer. There may also be some text which looks like gibberish which will also need to be left such as &lsquo; or &rsquo;.

Other examples:
  • With 'Welcome back {$SITE_NAME}', you would only translate the words 'Welcome back' and leave the '{$SITE_NAME}' intact.
  • With '{1} leads the usergroup &lsquo;{2}&rsquo;' you would only need to translate the words "leads the usergroup" as the software will replace '{1}' and '{2}' automatically (in this case with a user's name and a usergroup name).

Launchpad

(If you have a web designer such as ocProducts, you will want to ask them to perform these steps for you, if they haven't already done them)

Launchpad is an online system were multiple users can translate the same software, which can then be used by everyone. We would recommend downloading the translation from Launchpad first before working on the translation on your site. Some translations of the software may not be complete and it would be of a benefit to the whole community if any software translations were completed on Launchpad instead of locally.
To download and install the Launchpad translations you can follow the following step by step process:
  1. Go to https://translations.launchpad.net/ocportal/+translations.
  2. Register as a member if you already do not have an account or log in.
  3. Choose the version of ocPortal you have installed (if you're not sure, it will say on the front page of the Admin Zone).
  4. Click 'download' (this is a text link on the right hand side).
  5. Choose the PO file format and request Download.
  6. You will then be sent an email with a link in it.
  7. Save the file in the link.
  8. Extract the file (if you can extract all of the files into one directory). Usually this will contain many sub folders.
  9. Sort the different language files into Language folders:
    • Find all the files which end with the language code, ie. "-es.po" for Spanish or "-it.po" for Italian.
    • Copy these into a folder named with the relevant language code, in capitals (for example "ES" for Spanish, "IT" for Italian, etc.).
  10. Copy this new folder into the lang_custom folder within the webspace where your ocPortal installation is.
This will now have installed that specific language translation from Launchpad. To add more languages repeat points 9 and 10 for each language. When you edit content or add new content in ocPortal you should now be given a choice of languages you want to edit from those you have added.

You should also upload the attached file which ensures English is set to "Unicode", which is necessary for your website to be able to mix content from different languages without it looking corrupt.
Attachment
lang_custom/EN/global.ini
» Download: global.ini (24 Bytes, 33 downloads so far)


Allowing guests to choose language

You now need a way to be able to give your site visitors the option to view your newly translated website in another 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 – if you are an ocProducts client and have discussed internationalisation, it almost certainly is already built into your web design). 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.

Translating the remaining software

If the downloaded translation from Launchpad is not fully complete you may need to translate some of the language used on your site. To be able to change the text relating to the software and menus which display, you will need to go through each screen and change the visible text strings. This will need to be done on every visible page to make sure nothing is missed. To change the visible language strings on any page:
  1. Make sure you are viewing the site in your chosen language.
  2. In the site footer there is a drop down menu which is only visible to Admins. This is titled "Select context editing tool" as standard ("Select development tool" on older versions), although it may not be visible on custom themes. If you are not using the default ocPortal theme then you can enable it temporarily by adding &keep_theme=default to the end of the website address.
  3. Choose "Translate/Re-Phrase the software" from this menu. In newer versions you can actually choose which language (so you could actually have skipped the first step), in older versions it only lets you translate the one you are viewing.

This will take you to a page which displays the language strings which are used on the current page. Some of these are re-used across different pages, so changing them on one page will affect any other page that uses them. Thus you will not need to change them for every page separately. For example the word "Members" may appear on several pages, and once it has been translated once it should not need translating any more for the software.

There is another option, within the Admin Zone menu under the Style tab, entitled "Translate/re-phrase the software" which allows you to go in and manually edit the various full language files for every language you have installed.

A developer such as ocProducts can set up your site so that you get a Google Translate button next to each language string on these translation screens, and it takes under a second for each item to translate. If you don't have such a button on your site, enquire with the web developer.

Translating the content

There are two parts to editing the website content:
  1. Comcode Pages
  2. Other content, which can be translated by a link in the footer

Comcode Pages

A Comcode page is a page like your front page that consists mostly of static text that doesn't have any particular pre-defined content structure. This is contrasted to a page that is generated from some other form of content like a news article or news archive.

When you click the "Edit this page" link beneath a Comcode page it will give you the choice of which language to edit. This is how you can edit the Comcode page text, such as an introduction to your site or an about-us page. Pages in other languages will display the English text unless some changes have already been made. Obviously any subsequent copy changes you make to the wording, i.e. adding another sentence or paragraph, will need to be repeated for every language which you maintain a translation for if you want to keep your translations consistent.

Other content

Once you have translated the software and the static content on your website you will will want to translate any other content such as news articles or blog posts. There are two ways to do this:
  1. You can click the "edit" link when viewing the content item. Changes will save into the language you are currently viewing. The down side to this is that because the other language version has been edited after the English version, ocPortal will mark the English version as 'out of date' and in need of updating. Of course if you then edit the English version, the other language version will be marked as old, and so on. This is because ocPortal has no way to know whether you are making copy changes or doing translation.
  2. The better option is to use the "Translate the content" footer link, which will avoid the problem mentioned in point 1.

Images

Your web design may include some images with text in. Your web designer will need to have made translations of these images under ocPortal's mechanism for theme image internationalisation.

Newsletters

When you send a newsletter in ocPortal, you are asked what language to send it to users in.

Summary

We would recommend the following method to help ensure a complete translation:
  1. Download the language from Launchpad (actually if you have the time and resources, contributing to the translation here before downloading if it is not yet finished)
  2. Select your translation language and then go through each page on the website, translating the content one by one.
    • Click "Translate/rephrase the software" in the footer link
    • Click "Translate the content" in the footer link
    • If it's a Comcode page, edit the page in your chosen language
  3. Optional: Once you have completed this, if you feel the need for perfection, go to the Admin Zone, and click "Translate website content" under the Style section to translate any out standing website content (it could take some time though, and you may not mind about text buried very deep in the website functionality where users won't be looking).
Once all of the above sections are complete you should have a fully translated website. You will need to make sure any new content which is added has translations for each language you have added to your website by repeating the same process for that page.

See also