Multi Language Help System
Introduction
OM is a mission represented in different countries around the world. Any software which is developed for OM shall handle multi language user interfaces, help files and manuals. Furthermore it is a good idea that the user language is user depended and not country depended. If a French OM member has a temporary residence in England for example there is no reason against the requriement that he shall be able to use the french language ressources.
This page describes how to create, translate and deliver help page content and manual content focused on a technology which enables solidCRP and OM to do deliver the primary English documents by doing a minimum of administrative work for organizing the translations.
In the time gap between release of the orignal English document and the French translation, a French user shall be able to use the English ressources. Therefore a mechanism is required which checks a list of user dependend languages and language priorities and decides for the best document or comes up with a screen providing a selection list.
In the following the multi language document system for openpetra is based on the Open-Source-Software Wikimedia. This can be changed nearly at any time.
The Wikimedia-Software can be in installed on a V-Server, a real server and on a server farm and therefore it is scaleable to any size we need. The content of a Wikimedia-Installation can be exported into Wiki-Home-Versions and so after the documentation of a version is stable, it is possible to deliver it to an OM-Office directly or to join it with the delivered software version. Inside an OM-office there will be the possibilitiy to run a lan-server providing those information or the local host.
Now let us assume we have an openpetra dialog box serving a function called "function-x" and let us assume that the user hits the help button or the help menue function to invoke those page of the wiki, which handles the relevant documentation part in his relevant language.
Pressing the help button for example may either invoke the delivery of the pages:
- The x-function
- Beschreibung der x-Funktion
- Description du function de x
In this example three different URLs are available. In reality this can be some more (as much as languages are availiable).
The first step of creating a documentation is described easily. Someone has to write the original document directly into the wiki. This is a text like this one. The next step is to create one or more translation of this original and of course it can be put to this wiki too.
The user of the openpetra software has a button which may call an URL docServer.tld/languageSelection.php?function=x-function&version=1 (I do not write http... because this will force the wikipediasoftware to create a link!). This url is not a real wiki-link and requests the delivery of the content of a wiki page. In case of an English user language this may be docServer.tld/index.php?title=The_X_Function, in case of a German user language it may be docServer.tld/index.php?title=Die_x_Funktion and in case of a French user language docServer.tld/index.php?title=Le_function_de_x.
In the standard case of a browser requested page, the language decision shall be done by the value of the accept-language parameter in the browser which is used by the user. The following picture shows the dialog of a German Firefox.
The language in the top of the list is the most important and the others are possible options. The list of this parameters is stored in the "Accept-Language"-Parameter of the http-header and enables a content negotiation decision of the web server.
Using a wiki adds some difficulties because now the URLs are different. This requires a temporary redirect.
The set of iana-language-tags are shown here. The language tags are well defined. Using the list - get a look to the http-header - the possible languages are ordered (the factor q we can drop in this case) "de,en,en-us". So in our request docServer.tld/languageSelection.php?function=x-function&version=1 the French file will never been shown even it is the only one document. In the standard case of an apache webserver, the German file will be delivered if it is available and the rest will not be checked. Only if the German file is not available, the English variant may be delivered.
But now in the case of using a wikimedia-software we have to handle different document states. A document can be previous or released. So let us assume the user invokes his documents in the language order "de,en,en-us" and let us assume, the German document is a previous and non released translation of the previous English documentation. In such a case it may be a good idea to show a selection screen, to give the user the space to decide. Only if the file on the top of the list is released, the decision is unique.
Resume:
- The user requests docServer.tld/languageSelection.php?function=x-function&version=1
- If the first version in the list of available documentations is released, the server shall deliver this document directly
- Otherwise the server shall deliver a selection screen
- If only one file is availiable and the file is not released, the server shall show the selection screen to, because it is necessary to inform the user the status of the document.
The result ist quite simple. Any user provides it's own PC account. He selects his preferred browser and his preferred language - thoose parameters are relevant to drive the language decision for the help ressources and of course for the gui-language ressources too.
The translation tree and its groups
To handle the complete translation mechanism the following groups and group-policies may be used.
Software-User - This is a person who does not make any translations. So he/she shall only be able to post a text onto the discussion-page in order to ask something in case of trouble. In order to avoid spamming the user shall register himself and log in for doing this.
Translator - This person translates a text. Each translator has a set of pairwise from-to-languages. He translates from the "from-language" to the "to-language". So the translator shall be able to post text into a page tab (creating a new one). Furthermore he shall be able to define resp. set some parameters respondig to the document. The parameters are the document language (if the translater supports more than one to-languages, this value is not unique) and the version number. The implicitly created parameter version-type is allways set to "preview".
Language-Responsible - This person can add other language responsible to its group and remove them. He/she has all priviledges of the translation and furthermore can set the value of version-type to released.
Remark: It is not a problem that a language-responsible for English can add someone to the group to enable him to translate to French.
Buerokrat - This group already exists in the Wikimedia and he/she can add someone to the language-responsibility-group ore remove someone from it.
Let us assume an original document (or a set of documents) in English has been posted and finally released. No one knows about it and so a message to all translators and language-responsibles should be send. The best way of doing this is a mail to all members of the translator-group supporting the "from-language" English.
If this cannot actually be done by the wikipedia software, solidCRP will create a mailing list at source-forge to spread this information.
The best way to handle the translation is a universal translation from English to any other languages. But if someone needs the Italian document in order to translate to Greek then the released Italian document will become the original document for the Greek translation. In order of the information gap between the original document and its translation we shall avoid such situations.
Some examples
Let us give some Examples. The English pages assigned to function-x may be found in the page The x-function. Then we have access to the following files:
Small additionaly software
Based on this document we need a language-switch-software (lss) which enables to store a table containing
- a language-identifier
- a version number
- a preview-release-flag
- url for this case
Important is: The translator may insert a preview-url and the language-responsible a preview-url and a release-url into the database dedicated to one of his langugages in the to-list.
If someone changes something in the document, two cases are possible.
In case of a spelling mistake we have a minor edit and in this case even a release-version may be changed by a language responsible without informing thoose people who have allready translated thoose page. In case of a major edit we assume that a part of the documentation has been reformulated in more blow by blow. In this case it seems to be a good idea to inform all other persons who translated this page into an other language in oder to check if they have to change something too.
So this lss shall handle the complete translation tree for each page system like function-x.
Finally: The translation-tree for function-x may be different from the tree for function-y! Of course it may be necessary that function-x is translated from Italy to Greek as described above and the other problem function-y can be translated by someone who translates directly from English to Greek.
Therefore the lss may be a standalone CMS-Software and handles its own log-in-info (name, login-name, password and e-mail-adress) and:
- the language(s) the person is responsible for
- the language(s) the person can translate to
- the list of pages which are either translated or released by this person
But it may be better if it is possible to get this function by a wikimedia-plugin.
Beyond the already discussed minor and major edits, the modul function-x can be expanded in the software itself. In this case the version delivered in docServer.tld/languageSelection.php?function=x-function&version=1 shall be incremented.