Most Powerful Open Source ERP

Guideline Translation Best Practice

[out-of-date] Please use individual guidelines.
  • Last Update:2017-03-27
  • Version:002
  • Language:en

This document is to define what is considered as a good translation and to explain how to make a good translation. It introduces the different tools to be used and the process to follow for each tool to reach a good translation. It will also list translation crimes, which should be avoided. It does not explain how the translation must be tested.

Table of Contents

Definition of Good Translations

This section describes the characteristics of a good translation.

Completeness

This means that everything is translated and that there is no remaining untranslated word/sentence. Only the user interface PO File can be tested by a machine and proven to be complete, the Content PO file must be checked by humans, as described in the "How to test translations" document. You can read the How To Translate document to understand the translation procedure.

Unambiguous

Unambiguous means that users must not have any doubt about the meaning of a term. If a term triggers a debate between people (within Nexedi for example), it means that it is ambiguous, and must be changed. There are many financial/accounting terms, all of them have an equivalent in a local language, or different equivalents, which means that you will sometimes have to choose between different translation solutions. If you have to choose between different solutions, please consider this rule: always use the word which is the most used in your language, even if it is not the less ambiguous. This is the only exception to the Unambiguous criterion described in this paragraph.

Usable

If a translation is usable for users, then it is good. What is the goal of a translation? It is to make the program usable by users speaking a given language. If they use it and do not complain about it, then the translation is good. For this to be true, the translation must be approved within Nexedi first after the translation has passed the translation tests successfully. The acceptance of users comes after this, and confirms or denies this statement.

Documented

Documented means that each word has a proper description in the Glossary. The description should give the meaning of this word, and if needed, an example of where it is used. This rule only applies to English terms, that will be the basis of future translations. It is of course better to document each language in the glossary but this is not compulsory.

Universal

There is one exception to the "usable rule" and to the "unambiguous rule exception": the case of universal terms in ERP5. Whenever using a term which is less common or less accepted allows to create a common (yet innovative) vocabulary with consistent semantic across different business fields, we should prefer innovation and consistency. This rule must be used with care though. Here are some details:

ERP5 tries to be very generic in all its aspects. This is a recognized innovation of ERP5, acknowledged by IEEE scientific publications. It uses the same technical terms, the same modules and the same conventions for very different business fields. The workflow state "stopped" is for example used both for accounting and trade. If the "usable rule" or the "unambiguous rule exception" lead to a situation in which the same translated term (ex. Closed) refers to different technical terms in ERP5 (ex. stopped and delivered workflow states) depending on the business field, then translation breaks the universality of the ERP5 design and may even lead to confusion in the company: what will happen whenever accountants and sales people discuss about "Closed" documents, which are documents in the last workflow state for one group and documents which still need to be worked for the other group. Not only such a translation breaks the universality of ERP5 design but even creates a fake sense of commonality for terms with very different underlying semantic.

Translation Best Practices

This section is designed to explain what the translation best practices are. These best practices must be followed by any translator, this is the only way to lead to a "good" translation, as described in this document the above section, and have the translation pass the translation tests successfully, as described in the How To Test Translations document.

Work with the Localizer and a .po file

Both Localizer and .po file translations are needed. This paragraph will explain how to use the Localizer properly. In order to understand how to work on a .po file, please read the How To Translate document.

In order to do a live work, you will need both an Test Instance and an access to the Localizer: you can be given an ERP5 test instance after approval by Nexedi. If you want one for translation purpose, send your request by email to express-support@myerp5.com. The localizer helps you translate the terms of ERP5 and see the results in live.

How to use the Localizer

Access the localizer with Konqueror. Go to the test instance you will work on. Log-in with the admin account, in order to be able to reach the localizer. Reach the following page: https://www.myerp5.com/YOURSITEID/manage_main, and click on the Localizer.

Launch a browser and access https://www.myerp5.com/YOURSITEID/view. This is the address of your ERP5 test instance. When on your ERP5 test instance, login as simple user.

Once you are logged in, browse your instance. When you find an untranslated word, translate it in the localizer, in Konqueror, considering these two distinct parts of the Localizer:

  • Content: this section gathers all (almost all) the terms that are located in rolling menus of your instance. If you want to translate them, click on "erp5_content (ERP5 Localized content)".
  • User Interface: this section gathers everything that is not part of the content, eg words that are not in rolling menus. If you want to translate them, click on "erp5_ui (ERP5 Localized interface)".

Notes:

  • Ensure a language is selected. On the screenshot, French is selected. You will enter the translation here.
  • Above this field, the original term is displayed. Do not edit this field.
  • Use the search zone to find the word you want to translate (case sensitive).
  • Below the search you can see the search results. Click on the term you want to translate and after translating it, click on "Save"

Once a term is translated, you can refresh (F5) your Test Instance in your browser to see how it looks like.

Tips

Here are the two problems that you might face while trying to see the translation in your test instance:

  • Cache Problem: In order to solve this cache problem, I would recommend to open the portal_caches in the same browser as the localizer. In order to do so, you must reach your instance at the following address, and login as admin: https://www.myerp5.com/YOURSITEID/portal_caches/manage. Once you reached this page, click on "Clear all cache factories" to clear the cache of your instance. You can now go back to your browser and refresh your page again, the term should now be translated. (If it doesn't, check that you selected the appropriate language in the context menu bar or continue reading)
  • Translation scripts in ERP5 are still not perfect, which means that some modules do not apply the translations of the localizer. Therefore a term can be translated in a given module, but not in an other modules. This is not your fault, and you can do nothing about this.

Use the Glossary

The Glossary can be accessed at this address: https://www.myerp5.com/glossary. It is useful to use the glossary in order to harmonize the translation, especially if different people are working on translating the application. The Glossary should contain each term of the application that is part of the GUI PO File, along with description and context. This way, if you want to have more information about a term you do not know how to translate, you can refer to the Glossary and check the context or see whether the term has already been translated by someone else.

You can read the document How To Translate explaining how the Glossary can be used for translation purpose.

Do not work without documents and advice

This is a basic advice but not working alone is the key for achieving a good a translation. Indeed, once the basic terms have been translated, you will find out that ERP5 contains many specific terms related to those different fields: Accounting, trade, customer relationship management.

In order to make sure that your translation is correct, or if you have any doubt about a term and you do not find an answer in the Glossary, try to find an answer using the options of this list, and remember that this is better not to translate a term rather than translating at random:

Finally, if you have a real doubt about a word and can not find an answer in those tools, ask the people around you to help/advise.

Translation Crimes

The purpose of this section is to list and explain the behaviours that must be considered as translation crimes. Translation crimes must be avoided absolutely by translators of ERP5.

Never translate the glossary without looking at the application

Without context, it is impossible to translate ERP5, because a given word can have many different meanings, or can be either a noun, an adjective or a verb. If you do not look at the application during the translation procedure of the Glossary, you might give wrong Titles and Descriptions to certain terms. The best example is the Order word, that can be seen in those cases:

  • Order is used as a verb in Order workflow order_action transition.
  • Order is used as a noun for properties used for sorting, like int_index.
  • Order is used as a generic term for Purchase Order or Sale Order.

Conclusion: there should be 3 terms: Order Action, Sort Order, Order. Look at the context, find where the term is used in the application and what for. Once you have found this information, translate with the most precise word and unambiguous word you can.

Note for developers. Please try to write a complete description from now on, for each term that enters the glossary.

Never translate a PO file without looking at the application

Translating a PO file without looking at the application is a translation crime because it will generate bad terms, with wrong or inappropriate meanings. Same thing as for the glossary, if the context is lacking, do not translate the term, and ask for help of people who might know where the term is used. If you find a term that looks like bogus or unused in the application, please report this term.

Never work all alone without tools or advice

Almost nobody is able to know all the terms of an application and their appropriate translation, because working on translation implies that at least one of the two languages you are handling is not your native language. Working without tools or advice will obviously lead to inappropriate translations. To avoid this, you might need some help for your translation, for instance if you do not know how to translate a term. You can use the links listed above to look up translations in case you are in doubt on a specific translation.

Never forget that the original term can be bad

It is impossible to have a perfect translation, whenever the vocabulary used in the native language is wrong. Of course, an inappropriate original term will trigger off inappropriate translations.

If you think that a term is inappropriate in the native language of ERP5 (which is English), do not translate it. This term will be reported during the Test Procedure and worked on by the Team.

Translation Mistakes and Pitfalls

This section lists and explains the mistakes that have been done by the Nexedi during their first attempt to translate ERP5 into French. This paragraph may be useful in order not to make the same mistakes again when translating into other languages.

Glossary

The Glossary origin and structure itself proved to be difficult when translating ERP5.

Glossary Origin

According to the technical team of ERP5, the Glossary has been built backwards. Indeed, it has been extracted from the terms of the application, and it seems that the common sense would have recommended the opposite, which is built the Glossary first and built ERP5 based on this built Glossary.

As different people have been developing ERP5, without Glossary, there are some inconsistency in the terms that are used in English in ERP5. This results in duplicated terms, and a Glossary that must be cleaned up, which is quite a loss of time.

Glossary Structure

While thinking about how the translation should be tested, it appeared that the structure of the Glossary was not adequate:

Portal type is lacking: the absence of a column Portal Type in the Glossary results in bad context and then bad translations, and duplicated terms. The portal_type will be useful in the first test that will have to be taken, as described in the How To Test Translations document.

Lack of clear translation process

This section explains why a lacking translation procedure has created a mess in the translation. It will also list the different documents that have been created in order to provide translators with a good translation process to follow, in order not to make the same mistakes again.

Lack of experience

The lack of experience has been a problem, but as this was the first translation attempt, there could not have been any. Experience is shared in this document. But this lack of experience has lead us to lose considerable time, especially the lack of experience regarding proper translation tools, the Localizer and the PO files:

  • The Localizer is useful because it helps translate live, which means see the result of the translation in the application. It is then really appropriate when the context is lacking. The good process is to browse the application, and when a term is not translated, reach the localizer, search for the term and translate it.
  • The PO files are useful to see the completeness of a translation, as it will help you see the fuzzy and untranslated terms, which is not the case of the Localizer. On the other hand, it will provide you with less context than the Localizer.

Lack of testing procedure

For a long time there was no testing procedure for translation, e.g. no means to check the quality of the translation. The French translation has been released, even if not complete and not accurate. Obviously it has not been accepted by users either, because many of them complained that ERP5 was not translated.

Fuzzy Assignments

This chapter explains why assignments and organisation issues are part of the translation mistakes that have been done by the Nexedi team. This paragraph will describe these mistakes in order not to do them again.

Who does what?

We have been many to work on the French translation, but in the first attempts, without knowing exactly who was doing what, e.g. who was translating this or that module, etc. This means that instead of cooperating, by dividing the PO files into the proper number of translators, a unique PO files has been generated and worked on by different people of the team. But here is the problem:

  • What to translate? If someone is told to translate a PO file for example, he or she will not only translate the fuzzy and untranslated terms, but will also check the other terms, and sometimes will change a term that he or she think is not appropriate or bad translated. A good assignment on a PO file is then to split a PO file and ask a team member to translate the entire PO file.
  • Inconsistency: as the translators where working at random on the same PO file, without being assigned a specific module to translate, there have been some inconsistency in the translations. Indeed, we found out that some PO files had been processed by different persons from the team, resulting in inconsistency while merging the files. This mistake is not so current, and has been done maybe one time, and only during the first translation attempt, but needed to be mentioned here.

Developers/non developers

ERP5 is a complex application containing many complicated/specific terms that only skilled persons can translate. As the Glossary was sometimes lacking descriptions or context, or the context was explained in a technical way, non-developers translators have many problems to translate technical terms. This is the reason why technical terms must be described and translated by developers, or best, if those terms will not be seen by end-users, then those should be kept in English, with a proper description.

On top of that, it is very hard for a non-developer to translate such an application before he/she knows how it works. By understanding the way ERP5 works, a translator will easily find the context of a term.

Skills

PO files should have been split into separate skill based PO files, assigned to skilled persons. Some persons are able to translate accounting, some are not. Some persons are able to translate developer terms, some are not, etc. Asking many different translators to translate the application can be a real gain of time, but only if those translators are skilled into what they have been assigned to translate, or assisted enough by skilled persons in order to learn. This learning procedure will take more time but will be useful because a new person will in the end be considered as skilled.

Related Articles