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¶
#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.
#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.
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