Translating OxS

From PKP Wiki
Revision as of 10:08, 16 September 2010 by (Talk) (Finding the Files to Translate)

Jump to: navigation, search


OJS and OCS are multilingual systems, allowing journals and conferences to publish in a variety of languages. The Public Knowledge Project aims to support English, French, Spanish and Portuguese translations for both OJS and OCS. In addition, translations of both software packages have been completed by the community, and we welcome contributions at any time.

All text you see in a typical fresh OxS interface has been abstracted from the system code, and has in fact been retrieved from one of a number of XML locale files. These files can be found in folders using appropriate ISO locale codes (the Language Code Listing followed by the Country Code Listing), for example en_US for American English, or pt_BR for Brazilian Portuguese. This document will use en_US for its examples.

These locale directories will typically have XML files containing lists of message keys written in them: these message keys and their corresponding values correspond to template lines in the system code itself. The following set of message keys are taken from locale/en_US/locale.xml:

<message key="navigation.journalHelp">Journal Help</message>
<message key="navigation.home">Home</message>
<message key="navigation.about">About</message>
<message key="navigation.userHome">User Home</message>
<message key="navigation.login">Log In</message>
<message key="navigation.register">Register</message>

When the system needs to display a piece of text, it first determines which language should be displayed. The first place it checks is to see which language has been set as the site-wide default by the Site Administrator. If the user is currently looking at a journal, the system instead checks to see which language the Journal Manager has set as the default. And finally, if multiple languages have been installed it checks to see if the user has specified another language to be used instead of the default. More information on administering languages can be found in the section on checking language availability.

Once the system knows which language to display to the user it grabs the message key value from the locale file that belongs to that specific translation: that is, if it needs to display the text relevant to message key="navigation.journalHelp" from the above example, and knows that it should display this in English, it will look in locale/en_US/locale.xml for the appropriate key value, in this case "Journal Help". If the message key doesn't exist (if the locale file is missing that particular key, or doesn't exist on the system in the first place), the system will display the raw message key surrounded by hash marks:


If you ever see that kind of code on an OJS or OCS page, you know that the translation is incomplete. You can take a look at the section on translating to see how to complete it.

Checking Language Availability

You are advised to first check which languages are available from your version of OCS or OJS. If the language you want isn't listed, then check our website for availability.

Warning Warning:   We like to ship OJS and OCS with as many finished translations as possible, but we do rely on volunteers for this process, and we don't always have completed translations ready to ship by the time we hit a release date. At times, we opt to ship incomplete translations. Please note that availability in a stock install does not necessarily mean that that particular translation is 100% complete.

Checking Your Software for Available Languages

The first place to check on language availability is from within the software installation itself.

For both OJS and OCS: If you have System Administrator access, log in and go to the System Administrator User Home, and click the Languages link, which will take you to the site-wide languages administration page. This page has two main sections:

  • Under Language Settings you will find a drop-down box for your Primary Locale: this sets the default language across the entire site; users will be presented with this language by default, until they change their own language preference.

    You will also see a list of supported locales, with checkboxes next to them. The selected locales will be available for use by all journals hosted on the site, and will also appear in a language select menu on each site page (which can be overridden on journal-specific pages). If multiple locales are not selected, the language toggle menu will not appear and extended language settings will not be available to journals.
  • Under Manage Locales you will find a list of installed locales, as well as a list of new locales that haven't been installed.

    Beside each installed locale you will see: a link to reload locale, useful if you have made any changes to any locale files; and a link to uninstall locale, which will not remove locale files from your server but will remove them from the list of supported locales.

    At the very bottom, beside each locale that hasn't yet been installed, you will see a checkbox. To install a language, check the box next to its name and click Install. The page will reload and the locale will appear under Manage Locales.

    If a language is listed as available and installed from the Site Administrator's Languages administration page, you will still have to enable it for your journal or conference for it to be available to users. Log in as a Journal Manager or Conference Manager, and from your User Home click on Languages to visit the journal- or conference-specific language administration page. Here you will be able to set the primary locale for your journal or conference, and likewise enable supported languages to be used journal- or conference-wide. If you enable more than one language, users will be able to toggle between them via a drop-down menu on the sidebar.

Checking the PKP Website for Available Languages

The PKP keeps an up-to-date list of languages and contributors from the relevant project page.

Information is organized in a table, with the software version along the X axis and the list of languages on the Y axis. Clicking on a language name will take you to an individual language page, which will list the most recent contributors, and any other relevant information.

All languages fall into the following categories:

  • Complete: either bundled with that particular version of OCS or OJS, or are otherwise available for download from the list.
  • Needs Updating: these files may be included with the version you are using (the table will indicate this) but incomplete for some reason (they may be a version out of date but still relevant enough to be useful; or they may not have been 100% translated in the first place). If they are listed as not being included with the software version you are using, you can contact the last known maintainers to see if they have any recent files.

If you don't see the language(s) you are looking for listed on either of these lists, please consider undertaking the translation yourself. If you are interested in contributing in such a way, contact us for advice, or consult the rest of this document.

Installing a Language

Language packs are available in tar.gz archive format, and can be installed by following these steps (You will require software such as 7-Zip to decompress the downloaded file):

  • untar the archive to your OJS or OCS root directory on the server: this will place the translated locale files into the appropriate directories;
  • add the locale to registry/locales.xml using the following syntax:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE locales SYSTEM "../dbscripts/xml/dtd/locales.dtd">
    <locale key="de_DE" name="Deutsch (Deutschland)"/>
    <locale key="en_US" name="English"/>
    <locale key="es_ES" name="Español (España)"/>
    <locale key="fr_CA" name="Français (Canada)"/>
    (... and so on)
  • Log into your system as a System Administrator, and go to your Languages page;
  • Check the checkbox beside the newly-registered locale under Install New Locales and click Install;
  • After the page reloads, check the checkbox beside the newly-installed locale beside Supported Locales and click Save.

You will then need to either visit each conference or journal you are administering and activate the language from the Journal/Conference Manager Language page. You can do this by checking the box beside Supported Locales and clicking Save.

Warning: Visit your system information page (http://<your-site>/index.php/index/admin/systemInfo) and review your "registry_dir" variable to be sure you are editing the right locales.xml

Translating OJS and OCS

There are two ways to translate OJS and OCS: you can create a completely manual translation by writing locale files by hand; or you can use the Translator plugin, available in OJS 2.2/OCS 2.1 and above, to finish new translations or edit existing ones.

Creating a Manual Translation

Finding the Files to Translate

To translate OJS into an additional language by hand, first download the latest version of OJS or OCS to a computer (which doesn't have to be a webserver: this can be on your desktop) to extract the files just for translation purposes.

You will require software such as 7-Zip to decompress the downloaded file (e.g., ojs-2.2.3.tar.gz).

Opening the downloaded file with your decompression software will create a directory on your computer based on the downloaded file (e.g., ojs-2.2). Within this directory you will find the following list of subdirectories, where the XML files needing translation are located (en_US is both systems' default language, and by that nature always the most complete; we'll use it as the starting language for a translation):

OJS 2.2 files

  • locale/en_US: This directory contains the main locale file with the majority of localized OJS text.
  • dbscripts/xml/data/locale/en_US: This directory contains localized database data, such as email templates.
  • help/en_US: This directory contains the help files for OJS.
  • registry/locale/en_US: This directory contains additional localized information such as a country list.
  • rt/en_US: This directory contains the Reading Tools.
  • plugins/[plugin category]/[plugin name]/locale, where applicable: These directories contain plugin-­specific locale strings.

OJS 2.3+ files

Starting in OJS 2.3, the main locale file in locale/en_US has been split into a number of different locale files; the old email templates file has also been moved from the dbscripts location to the locale/en_US directory.

  • locale/en_US: This directory contains a number of locale files, including the emailTemplates.xml locale file. All files should be translated.
  • lib/pkp/locale/en_US: This directory contains locale files with keys that apply to our entire PKP suite of applications. All files should be translated. It may be that a translator for another application has already translated these files for you.
  • help/en_US: This directory contains the help files for OJS.
  • registry/locale/en_US: This directory contains additional localized information such as a country list.
  • rt/en_US: This directory contains the Reading Tools.
  • plugins/[plugin category]/[plugin name]/locale, where applicable: These directories contain plugin-­specific locale strings.

Editing the Files

On opening the XML files, you will notice commonalities between each file: Commented-out topmatter (anything appearing in tags) which you can safely ignore, and then various types of XML tags. There may also be instructions for each locale file, placed in a comments field.

The following XML entity exists in some, but not all of the XML files that you can translate:

<locale name="en_US" full_name="U.S. English">

This should be change to the language you are translating to, eg. French:

<locale name="fr_FR" full_name="Français">

Note: If you notice reference to a specific language in any of the comments fields, feel free to change the reference to your language, although it's not strictly necessary.

Next you will encounter the meat of the locale files, the message keys and their corresponding values. For example, the text that is to be translated in locale/en_US/locale.xml begins like this:

<message key="common.and">and</message>
<message key="common.between">between</message>

Only the text that sits between the XML tags is in need of translation. Here you can see how that text has been translated into French, after which it has been saved in a file named locale/fr_CA/locale.xml:

<message key="common.and">et</message>
<message key="common.between">entre</message>

Saving and Properly Placing the Files

Once you have translated the necessary XML files, they will need to be placed in an appropriately named subdirectory, using the ISO locale codes for your language and country (e.g., the files in locale/en_US are translated into French and saved in a subdirectory named locale/fr_CA).

The only critical files that need translation for the system to function properly are found in locale/en_US, dbscripts/xml/data/locale/en_US, and registry/locale/en_US.

New locales must also be added to the file registry/locales.xml, after which they can be installed in the system through the site administration web interface.

Using the Translation Plugin Tool

OJS 2.2 and OCS 2.1 onwards come with a translation plugin that makes the task of updating incomplete translations much easier. You can also start a new translation from scratch, although this takes a bit more work initially.

To enable the plugin, log in as a Journal Manager and go to User Home and then System Plugins; you'll find the Translator plugin listed with the generic plugins. Click on the plugin's Enable link. To access the plugin, return to the System Plugin page, scroll down to the plugin, and click the newly-available Translate link.

You'll now see a list of available (already-installed) locales, and three available actions: Check, Edit and Export.

Checking a Translation

You can check the translation's completeness by clicking the Check link: this will show you a list of missing locale files; keys missing from existing locale files; extra (unneeded) keys; suspicious key lengths (if your translated key value is substantially longer than the English default); and also missing or extra system emails.

If you are missing a locale file, the plugin will allow you to create one and translate the key values from the English default by entering new values against old values into relevant fields. Any other error will display the error message, plus the offending key value in an editable field.

Note: You may be initially surprised by the number of missing locale files: every system plugin requires an individual locale file for its interface, and if you aren't going to be using them you don't have to worry about translating them.

Editing a Translation

If you already know where an error is, you can click the Edit link beside the language name you need to fix, and then click the Edit link next to the specific locale file (please note: clicking the locale filename itself will link you directly to the locale file, which is downloadable).

You will be presented with a list of all keys in that locale file, with their English values alongside your translation values. You can edit your translation values directly here, and save your results, by clicking in the translation value field and making any necessary changes.

If you know the specific key you want to change (say "navigation.journalHelp") enter the key into the search field at the top of the table and press Search: you will be taken to the appropriate page, with the key/value highlighted in yellow.

You can also delete any key from the locale file by clicking the Delete link next to it. Please note, however, that you can't currently add a new key with the Translator plugin: if you do delete a key only to need it later, you will have to add it manually (ie., by editing the file on the server).

Exporting a Translation

You can export a translation by clicking the Export link across from the language name on the Translator plugin page: the system will compress all locale files for that one translation to a downloadable tar.gz package. This is especially useful if you need to migrate a newly-translated language to another OJS or OCS environment, or if you would like to contribute your changes back to the PKP.

Starting a Translation From Scratch

Using the Translation plugin to start a translation from scratch is a little more involved than editing an incomplete, installed translation. You'll need to manually create and upload the main locale file (locales/[your_LANG]/locale.xml) and email templates file (dbscripts/xml/data/locale/[your_LANG]/email_templates_data.xml), and enter your new language into registry/locales.xml, after which your language will appear in the list of editable translations when you visit the Translator plugin. Once this is done you can add new locale files as per the above instructions, and you'll even be able to edit the above two files.