Most Powerful Open Source ERP

ERP5 Guideline Translation

Conventions on how to make quality translations.
  • Last Update:2017-04-11
  • Version:001
  • Language:en

Table of Contents

Introduction

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.

Definition Of A Good Translation

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.

Recommendation

#

Documentation Document Should Have License Specified

Every document visible to the general public should eventually have a licence, defining the scope to which a document can be used outside of the scope of Nexedi.

Documents which explain how to do something will be made available under GFDL license while documents that explain why are CC-NC-SA. The differences are explained here.

#

Document Should Have Explicit Predecessors And Successors Defined

ERP5 provides an explicit (you declare manually) and implicit (used internally) way to cross-reference related documents. Related documents can be:

  • Predecessors - the current document is linking to the related document
  • Successors - the current document is linked from the related document
  • Similar Documents - documents with similar content

Please make use and explicitly add related documents to improve the quality of the overall document and documentation structure. This might at some point also be done automatically based on links placed in a document.

Applicable/Referenced documents are only used in internal documents and have separate guidelines. At some point they should be merged with successor (referened) and similar (applicable) documents.

Rule

#

Document Title Uses Capitalized Keywords Prefixed By Publication Section

Document Titles will be used on links and table of contents as well as auto generated tables. They should also work standalone and be self explanatory (compared to the short title, which is missing context (eg. Publication section). Use capitalized keywords for the title and prefix it by the documentation publication section.

Good Examples:

Guideline on Authoring Content
How To Create A Documenation Document

Bad Examples:

Create Property Sheet
Create a property sheet
#

Documentation Document Anchor Uses Software And Publication Section Split By Hyphen

Anchor references are more restricted when creating documentation documents than when naming generic content. The anchor must be a lowercase software product (like "erp5" or "slapos") followed by a hyphen and a documentation publication section. Multi word publication sections are written as single Camelcase word

Good Examples:

erp5-HowTo
slapos-TechnicalNote
erp5-Tutorial

Bad Examples:

SlapOS-how-to-create-property-sheet
ERP5.HowTo.Create.Property.Sheet