Multi Language Help System: Difference between revisions

From OpenPetra Wiki
Jump to navigation Jump to search
(Created page with '=== 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, hel…')
 
 
(12 intermediate revisions by 2 users not shown)
Line 9: Line 9:
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.  
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.  


A 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.
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.  
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.  
Line 17: Line 17:
# The x-function
# The x-function
# Beschreibung der x-Funktion
# Beschreibung der x-Funktion
# Description le function de x (oder ähnlich)
# 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).  
In this example three different URLs are available. In reality this can be some more (as much as languages are availiable).  
Line 35: Line 35:
Using a wiki adds some difficulties because now the URLs are different. This requires a temporary redirect.
Using a wiki adds some difficulties because now the URLs are different. This requires a temporary redirect.


[http://www.iana.org/assignments/language-tags 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/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.  
[http://www.iana.org/assignments/language-tags 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 which is found on the top of the list is released, the decision is unique.  
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:  
Resume:  


# The user requests docServer.tld/function=x-function&version=1  
# 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  
# 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
# Otherwise the server shall deliver a selection screen
# If only one file is availiable, the server shall show the selection screen to, because it is necessary to inform the user the status of the document.
# 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 ===
=== The translation tree and its groups ===
Line 50: Line 52:
To handle the complete translation mechanism the following groups and group-policies may be used.
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.
'''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 pairweise from-to-languages. He translates from the "from-language" to the "to-language". So the translator shall be able to 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 uniqe) and the version number. The implicitly created parameter version-type is allways set to "preview".
'''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 translator and furthermore can set the value of version-type to released.
'''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.
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.
Line 60: Line 62:
'''Buerokrat''' - This group already exists in the Wikimedia and he/she can add someone to the language-responsibility-group ore remove someone from it.
'''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-responsible should be send. The best way of doing this is a mail to all members of the translator-group supporting the "from-language" English.
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.
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 form 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. SolidCRP will create a separate mailing list to organize this task, but the "language-responsible" with the to-language Italien are responsible for the content of this list.
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 ===
=== Some examples ===
Line 70: Line 72:
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:
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:


# [[https://dev.solidcrp.com/wiki/index.php?title=The_x-function&oldid=21 Previous-Version 1]]
# [[https://sourceforge.net/apps/mediawiki/openpetraorg/index.php?title=The_x-function&oldid=1101 Previous-Version 1]]
# [[https://dev.solidcrp.com/wiki/index.php?title=The_x-function&oldid=22 Release-Version 1]]
# [[https://sourceforge.net/apps/mediawiki/openpetraorg/index.php?title=The_x-function&oldid=1102 Release-Version 1]]
# [[https://dev.solidcrp.com/wiki/index.php?title=The_x-function&oldid=23 Previous-Version 2]]
# [[https://sourceforge.net/apps/mediawiki/openpetraorg/index.php?title=The_x-function&oldid=1103 Previous-Version 2]]
# [[https://dev.solidcrp.com/wiki/index.php?title=The_x-function&oldid=24 Release-Version 2]]
# [[https://sourceforge.net/apps/mediawiki/openpetraorg/index.php?title=The_x-function&oldid=1104 Release-Version 2]]


=== Small additionaly software ===
=== Small additionaly software ===
Line 88: Line 90:
If someone changes something in the document, two cases are possible.  
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 languagae 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 in an other language in oder to check if they have to change something to.  
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.  
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 than the tree for function-y! Of course it may be nessessary 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.
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 CSS-Software and handle its own log-in-info (name, login-name, password and e-mail-adress) and:
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 is responsible for
Line 102: Line 104:
But it may be better if it is possible to get this function by a wikimedia-plugin.
But it may be better if it is possible to get this function by a wikimedia-plugin.


Beyond the allready 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/function=x-function&version=1 shall be incremented.
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.

Latest revision as of 01:27, 15 December 2010

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:

  1. The x-function
  2. Beschreibung der x-Funktion
  3. 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.

Language-Selection-of-FF.jpg

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.

Http-request-header.jpg

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:

  1. The user requests docServer.tld/languageSelection.php?function=x-function&version=1
  2. If the first version in the list of available documentations is released, the server shall deliver this document directly
  3. Otherwise the server shall deliver a selection screen
  4. 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:

  1. [Previous-Version 1]
  2. [Release-Version 1]
  3. [Previous-Version 2]
  4. [Release-Version 2]

Small additionaly software

Based on this document we need a language-switch-software (lss) which enables to store a table containing

  1. a language-identifier
  2. a version number
  3. a preview-release-flag
  4. 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:

  1. the language(s) the person is responsible for
  2. the language(s) the person can translate to
  3. 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.