Sign up
Sign up

Translation of the UI and the contents

This page includes technical information required by the CommonSpaces members that contribute to the translation of the user interface (UI) of the CommonS Platform and participate to the authoring of its contents. Another help page presents in a simpler way the main concepts related to internationalization.

Translation of the User Interface

In principle, the user interface (UI) of the CommonS Platform can be translated in several languages, assuming that the developers have properly "marked" all language-dependent strings of text. Most of said strings occur in "page templates", being essentially HTML code, and in Python modules, since this is the programming language we use. Some of the templates and of the modules belong to the core Django framework, but they have already been localized to many languages, including French, Italian, Portuguese and many others.

Translating the CommonS Platform is not a one time task; it is an incremental task, to be coordinated with other development tasks, but most of the work can be concentrated near the end of major development steps.

The translation process based on Transifex

For translating most of the language-dependent strings in the UI, we use Transifex, a well-known service that should be free for open projects; in any case, the first month of use is free for all people.

We at LINK, after registering as individuals, created a commons-platform project on the Transifex portal; defined English as source language; defined French, Italian and Portuguese as target languages. Then, awarded some roles (translator or revisor) to registered users on the commons-platform project. More recently translation sub-projects have been added for Arabic, Catalan, Croatian, German, Lithuanian, Russian and Spanish.

The translation process is structured as follows:

  1. a Django tool extracts from the code of the CommonS platform the language-dependent strings in the source language and writes them, in an exchange format, to a text file with .po extension
  2. we upload the source .po file to our project on Transifex
  3. translators and revisors use the Transifex user interface for translating the source strings (more than 1000) one after the other
  4. we download an ouput .po file containing both the source strings and those translated in a target language
  5. another Django tool processes the output .po file and produces an equivalent file that Django is able to use
  6. we restart the web server, so putting the translation online.

After some time, when there are many new or modified UI strings in the code of the CommonS Platform, all steps in the process above have to be repeated. Transifex is smart enough to keep still valid translations, so that at each iteration the translators have to do or redo only a few percents of the translation work.

It is not necessary to wait for the translator(s) to terminate their task, in order to proceed with points 4 to 6 of an iteration; partial feedback is useful to point out problems deriving from errors in the source (misspellings and short strings difficult to translate out of context) and poor translations, possibly due to problems in the source.

The files mentioned at point 2. of the translation process are not user-friendly, since they are intended for machine processing; however, they are plain text files with just some syntactic sugar. They can be open, read and, with some care, also edited with any text editor. Their contents are divided into blocks, each including a source string (after the 'msgid' prefix) and its translation in the language concerned (after the 'msgstr' prefix), plus "context" information. In any case it is possible tu use those .po files to get an idea of missing and questionable translations, and to know where each string comes from (UI templates and/or  Python modules).

All the translation files for the UI strings are archived in an GithHub repository, together with almost all software of CommonSpaces, at the address https://github.com/gtoffoli/commons/tree/master/locale; for example, the .po file for French is at the addtrss https://github.com/gtoffoli/commons/tree/master/locale/fr/LC_MESSAGES. Just a warning: .po files in the GithHub repository are always aligned with the online version of the CommonSpaces UI but may not include the result of recent work done on Transifex by translators and reviewers.

Translation of the Vocabularies

We call vocabularies lists of controlled values that can be assigned to a field in a data object; for example, Education level or Known languages in the User profile. Currently, we use less than a dozen vocabularies in the Platform, each including from 2-3 to 15-20 entries; the Tags vocabulary is an exception, in that it includes many dozens of entries.

Translating the vocabularies is not an extensive work, but it requires some care, since poor choice and/or translation of vocabulary entries can hinder cataloguing and search of educational resources.

A vocabulary is a stable content; new entries are added only when some new need arises and, as a rule, entries are never deleted.

To translate vocabularies we use Datatrans, a basic support tool integrated inside the Platform. To use it, you need to be a registered user of the CommonS Platform and to be member of the Translations and Testing project.

Access the Datatrans tool by writing the url http://commons.commonspaces.eu/datatrans in the address box of the browser. Then

  • find, in the summary page of the Datatrans tool, the section related to the data Model (type of content) that you want to translate
  • click on the "change" link right of the name of the language you want to translate to.

For each translatable data field of a specific type of data object, Datatrans lists all the current values of those fields in text boxes: in the left half of the page are the boxes with the text in the source language (English in our case), while initially empty text boxes for a target language are shown in the right half.

A list follows of the vocabularies that we translate with Datatrans; each sublist is prefixed with the name of the content type(s) that uses the listed vocabularies:

  • User profile: education level, education field, professional status, professional field, social network
  • Project: project type
  • (external) Tepository: repository type, repository feature
  • OER and Learning path: level, educational material, media type, accessibility feature, license (terms of use)
  • (several content types): language, subject area

NOTE: the translation of Tags has been suspended temporarily.

Translation of contents

Translatable contents and reference language

While vocabularies are managed only by the Administrator of the Platform, other contents can be created and/or translated by other users. Each content object can have

  • language-independent content fields; e.g.: a numerical score, a date, an URL, a street address
  • fields whose values can only be selected from a specific vocabulary; as seen above, vocabulary entries are being translated as a distinct task
  • free-text fields, both plain-text and rich-text fields, that one could want to translate between the 3 languages (currently) supported by the CommonS Platform.

All translatable contents have a reference language. As a rule, in order not to mix up things, a translatable content should always be edited by using the same language, its reference language; even if you own editing rights on a piece of content, you won't find the edit icon   if the current UI language is different from the reference language (*).

A dedicated translation view is available for the following content types

  • Projects, external Repositories, Learning paths, Path nodes
  • Help pages and Info pages, Blog articles, other editorial contents.

These are the features of the translation view:

  • new - September 2018: only translation to languages know to the translator is supported (as declared in the user profile)
  • it includes only translatable fields
  • all language versions of a field are shown in the same page, with different labels
  • the source version of a field (the one in the reference language) is read-only despite its appearance
  • the translation of each field in each target language must be saved individually.

(*) In fact, you will be able to cheat, by first opening the edit view and then changing the current UI language, but this has the side effect, usually undesired, of changing the reference language of the content.

Translation of the metadata of projects and educational resources

The following are the language-aware (translatable) free-text fields in the data model of some content types:

  • Project: name, short description, longer description
  • external Repository: name, short description, longer description
  • OER: title, abstract or description, other info to identify/access the OER
  • Learning path: title, objectives, description
  • Path node: label, text content.

For these content types, the reference language equals the "original editing language"; for each content, this is the UI language that was active when it was created and that should be used to edit (modify) it (**). Since the machinery for translating contents has been added to CommonSpaces when many contents were already there, some contents have an "unknown" original editing language: the first edit operation will determine its value.

If you have translation rights on a content, and the UI language is compatible with its reference language, you should see the translation icon   right of the content title. Currently, editing rights and translation rights coincide; in future, we could introduce a translator role to allow clever and trusted translators to perform translations of others' contents.

(**) If, for any reason, your content has a wrong reference language, you can change it by recurring to the trick mentioned in a note to the previous sub-section.

Translation of Help pages and other Info pages

These pages are stored in the database as objects including two translatable fields: Title and Content (the text body). By convention, their reference version is always the English one.

These contents can be created and maintained by the Administrator of the Platform and by a few other users, currently the mebers of the "Translaton and testing" project.

It would be possible to translate Help and Info pages with Datatrans, but this tool doesn't support a rich-text editor, and translating text fragments embedded in HTML code, without breaking the code itself, is not so easy. For this reason we implemented an approach to the translation of the Help pages and of other Info pages similar to that available for the educational resources.