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.
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 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.
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 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.
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
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
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
firstname.lastname@example.org. 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)".
- 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.
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
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.
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.
The Glossary origin and structure itself proved to be difficult when translating
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.
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
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.
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.
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.
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.