[Sugar-devel] Multilingual Help activity: which localisation tools (was Re: Potential volunteer offering technical writing)

[samy boutayeb]

Hola Gonzalo,

> >
> We do not have translations in Help Activity.
> And is not a good idea use the same tools/strategies to translate a few
> strings in a activity
> and a full text document.
> 
Quoting Martin in a previous post, Id like to say "Yes and no" ;-)

I agree with you that we have 2 different types of activities. 
My point is that, altough we are faced with 2 different cases, it makes
sense to use a common reference (in the form of a so called "translation
memory", which refers to the content" of the activity) and, why not, a
set of common tools designed to manage this content.

Let's me illustrate my argumentation with the exemple of the FotoToon
activity [1] and of the potential corresponding chapter "Fototoon" of
the Help activity, and in particular from a triple point of view: from
the developer's perspective (which I am not. As you are the developper
of this activity, Gonzalo, please feel free to correct me if my naive
understanding is incorrect), from the translator's/localizer's
perspective (which I happen to be) and from the user's perspective.

1/ Developper
* FotoToon Activity: You develop fonctions and commands which should be
executed from a graphical user interface (with UI elements, as buttons,
menus, tooltips, etc. and eventually a help file, both online and
offline. You provide to this end a set of text strings, which are
embedded in your code.

Examples: "Add Whisper", "Add Box", "Bold", "Save as Image"
* Help Activity: The documentation writer writes a chapter "Fototoon"
dedicated to the corresponding activity "FotoToon". The document
consists of a succession of whole sentences, which refer to the
functions of the "FotoToon" activity and uses to this end :
- simple text
- screenshots (located between chapters)
- names of functions/commands (located in the sentences)
- symbols of the user interface (located in the sentences)

2/ Translator/localizer 
* FotoToon Activity: You provide the translators/localizers (one for
each target language) a list of translatable text strings (in form of a
po file) which you extract from your code.
Then, each translator provides with the equivalence of your strings in
his respective language:

Example (French):
4	Add Whisper	Ajouter un chuchotement
6	Add Box		Ajouter un cartouche
10	Bold		Gras
13	Save as Image	Enregistrer sous une image

For this task to be achieved, a "localization tool" has proved to be
efficient, helping to manage a bi-/multilingual localization project,
including various consecutive releases of the activity/program. Here is
the key-word "consistence".

File type: po file (bilingual text file of strings backed up in a
translation memory)

* Help Activity:
The document (consisting of chapters) is divided in sentences. Those may
embedd symbols (non editable) and names of functions/commands, which are
localizable and should be consistent with the localized version of the
strings of the "FotoToon" activity, as they refer to the GUI which is
displayed by the user, according to the locale (EN-US, ES-UY, FR-FR,
etc.) selected.
This is where the "translation memory" function is useful, especially if
the localization workflow includes the translation of the names of the
GUI elements. This is not mandatory, then a variant consists in mark the
GUI elements as variables, which are merged later with the content of
the po file.

File type : (a) text document (either 2 monolingual documents or one
bilingual document in with the sentences are segmented by the
localization tool and backed up in a translation memory).
(b) 2 sets of screenshots (one for each language)

3/ User
* FotoToon Activity: The user "plays" with the "FotoToon" activity in
the language set at the system level.
* Help Activity: The user reads/searchs/browses the Help activity in the
language selected. The screenshots and the names of the functions should
match the GUI displayed.

My conclusion: altough the standard activities and the Help activities
have distinct use cases (for the developer, the translator/localizer and
the user), and use different contents (single strings versus complete
sentences plus screenshots and symbols), from the localization point of
view, it makes sense to use a common localization tool and a common
"translation memory" in order to achieve a consistent experience for the
developer, the localizer and the user.
The fact that actual localization tools are able to manage efficiently
those different contents speaks in favor of a sigle translation memory
and, for the sake of simplicity, of a single localization tool.

Kind regards,

Samy

> Include multiple languages in the Help activity does not scale.
> 
> We can use get-books/pathagar to resolve the multiple languages and the
> infinite storage problem.
> 
> I think the first problem is have the updated manuals, and can be done in a
> few days by a group of volunteers.
> 
> Gonzalo
> 

[1] http://activities.sugarlabs.org/fr/sugar/addon/4253
[2] 
[3]
http://translate.sugarlabs.org/fr/honey/fototoon.po?view_mode=translate
[]