Difference between revisions of "Translation for developers"

From Kiwix
Jump to navigation Jump to search
(add template)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Beside the pure [[translation]] part of the work, the '''Kiwix source code needs to be synchronized with Translatewiki'''.
{{translations}}
<translate><!--T:1-->
Beside the pure [[{{ll|translation}}]] part of the work, the '''Kiwix source code needs to be synchronized with Translatewiki'''.
</translate>


This synchronisation with Translatewiki needs three type of operations:
<translate><!--T:2-->
* ''Add a string'' to Kiwix and Translatewiki, ie. introducing a dynamic string which will be replaced by the corresponding translation.
This synchronization with Translatewiki needs three types of operations:
* ''Add a string'' to Kiwix and Translatewiki, ie. introducing a dynamic string which will be replaced by the corresponding translation at the runtime.
* ''Update the Kiwix strings'' with the translations coming from Translatewiki.
* ''Update the Kiwix strings'' with the translations coming from Translatewiki.
* ''Add a new Translatewiki full translated language to Kiwix''.
* ''Add a new Translatewiki full translated language to Kiwix''.
</translate>


== Requirements ==
<translate>== Requirements == <!--T:3-->
You need a GNU/Linux Operating System. This is possible to do also that on other operation systems, but this is more complicated to get a working environment.
You need a GNU/Linux Operating System. It is possible to do it in another operating system, but it is more complicated to get a working environment.
</translate>


<translate><!--T:4-->
You need to have a few things in mind:
You need to have a few things in mind:
* Kiwix translation files are all in the "kiwix/chrome/locale" directory.
* Kiwix translation files are all in the "kiwix/chrome/locale" directory.
* There is two types of translation files to translate the User Interface (Have a look to the *.js and *.xul file in kiwix/chrome/content/main to understand how it works):
* There are two types of translation files to translate the User Interface (Have a look at the *.js and *.xul files in kiwix/chrome/content/main to understand how it works):
** "main.dtd" which provides translations for all *.xul files
** "main.dtd" which provides translations for all *.xul files
** "main.properties" which provides translations for all *.js files.
** "main.properties" which provides translations for all *.js files.
* Translatewiki translations are imported separately in the Kiwix code repository on time a week and we always need to synchronize thus files with Kiwix code in both direction (KW->TW and TW -> KW).
* Translatewiki translations are imported separately in the Kiwix code repository once a week and we always need to synchronize those files with Kiwix code in both directions (KW->TW and TW -> KW).
</translate>


'''WARNING: Before any modification of Kiwix source code, update your local code repository with "git pull origin master".'''
<translate><!--T:5-->
'''WARNING: Before any modification of Kiwix source code, update your local code repositories with "git pull origin master" in each one of them.'''
</translate>


== Checkout the code and start Kiwix ==
<translate>== Checkout the code and start Kiwix == <!--T:6-->
</translate>


Before starting to work on the integration of new strings in the Kiwix code, it's preferable to [[compilation|achieve to compile Kiwix]]:
<translate><!--T:7-->
Before starting to work on the integration of new strings in the Kiwix code, it's preferable to [[{{ll|compilation}}|achieve to compile Kiwix]]:
* Get the unstable code
* Get the unstable code
* Compile it like
* Compile it
* Run it by going to the kiwix subdirectory and launching ''kiwix''.
* Run it by going to the kiwix subdirectory and launching ''kiwix''.
</translate>


''Remark: If you are not able to compile Kiwix, or do not have xulrunner available (is the case for example on Ubuntu Oneiric and further) you will still be able to be able to start kiwix and get an interface although the application won't work correctly, but that's enough for example to manipulate the XUL files. In this case you will have to make a few additional stuff like add "MaxVersion=42.*" as new line to kiwix/application.ini and launch Kiwix using this command in the "kiwix" directory "firefox -app application.ini"''.
<translate><!--T:8-->
''Remark: If you are not able to compile Kiwix, or do not have xulrunner available (is the case for example on Ubuntu Oneiric and further) you will still be able to start kiwix and get an interface although the application won't work correctly, but that's enough for example to manipulate the XUL files. In this case you will have to make a few additional steps like add "MaxVersion=42.*" as new line to kiwix/application.ini and launch Kiwix using this command in the "kiwix" directory "firefox -app application.ini"''.
</translate>


== Add a string to the translations ==
<translate>== Add a string to the translations == <!--T:9-->
</translate>


=== Find a string to localize ===
<translate>=== Find a string to localize === <!--T:10-->
</translate>


<translate><!--T:11-->
Go through the *.xul and *.js files to find hardcoded strings (in English).
Go through the *.xul and *.js files to find hardcoded strings (in English).
</translate>


If you find one you need to find a string identifier (foobar for example), have a look to the already localised string to see how it should looks like. the most important to know is that in the *.xul files, it should looks like "&foobar;" and in the *.js like "getProperty('foobar')".
<translate><!--T:12-->
If you find one you need to find a string identifier (foobar for example), have a look to the already localized string to see how it should look like. The most important to know is that in the *.xul files, it should look like "&foobar;" and in the *.js like "getProperty('foobar')".
</translate>


=== Translate it in the master language English ===
<translate>=== Translate it in the master language English === <!--T:13-->
</translate>


You will need to do that on two place. First in the "kiwix/chrome/locale/en/main/" main.dtd or main.properties files. In that way the Kiwix application knows what to display if the user interface language is English.
<translate><!--T:14-->
You will need to do that on two places. First in the "kiwix/chrome/locale/en/main/" main.dtd or main.properties files. In that way the Kiwix application knows what to display if the user interface language is English.
</translate>


=== Update Translatewiki files ===
<translate>=== Update Translatewiki files === <!--T:15-->
</translate>


But you also need to tell Translatewiki to add this string in the list of string it has to provide (for the Translatewiki translators) to translate. For that you need to checkout an other part of Kiwix code repository. Please run outside of your local kiwix code directory following console command:
<translate><!--T:16-->
But you also need to tell Translatewiki to add this string in the list of string it has to provide (for the Translatewiki translators) to translate. For that you need to checkout another part of Kiwix code repository. Please run outside of your local kiwix code directory following console command:
</translate>


<source lang="bash">
<source lang="bash">
svn co https://kiwix.svn.sourceforge.net/svnroot/kiwix/maintenance_tools/translatewiki
git pull origin master
</source>
</source>


<translate><!--T:17-->
You have now on your computer the translatewiki translations. What you need is only to update the "en" file which is the master language file for Translatewiki. So simply add your new string following the examples of other already inserted strings and commit your "en" file.
You have now on your computer the translatewiki translations. What you need is only to update the "en" file which is the master language file for Translatewiki. So simply add your new string following the examples of other already inserted strings and commit your "en" file.
</translate>


<translate><!--T:18-->
Someone from Translatewiki check each week the "en" file for new strings and synchronized Translatewiki with this file if necessary.
Someone from Translatewiki check each week the "en" file for new strings and synchronized Translatewiki with this file if necessary.
</translate>


=== Create stub translation of you new string for all languages ===
<translate>=== Create stub translation of you new string for all languages === <!--T:19-->
</translate>


The last thing you need to do is creating stub translation of your new localised string for all supported user interface languages in Kiwix. If you do not that, Kiwix won't be able to work correctly in another language as English.
<translate><!--T:20-->
The last thing you need to do is creating stub translation of your new localized string for all supported user interface languages in Kiwix. If you don't do that, Kiwix won't be able to work correctly in a language other than English.
</translate>
 
<translate><!--T:21-->
For that purpose you need to use the TW2PL.pl script (this is a perl script, so perl needs to be installed) like following (go in the translatewiki file directory):
</translate>


For that purpose you need to use the script TW2PL.pl (this is a perl script, so perl needs to be installed) like following (go in the translatewiki file directory):
<source lang="bash">
<source lang="bash">
./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw
./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw
</source>
</source>


=== Commit the new Kiwix translation files ===
<translate>=== Commit the new Kiwix translation files === <!--T:22-->
Now, all the locale file in kiwix/chrome/locale should be update and you should have a lot of (modified) files listed by typing:
Now, all the locale file in kiwix/chrome/locale should be updated and you should have a lot of (modified) files listed by typing:
</translate>


<source lang="bash">
<source lang="bash">
svn status kiwix/chrome/locale
git status kiwix/chrome/locale
</source>
</source>


<translate><!--T:23-->
After checking everything is OK, you can commit your modifications: ie. the kiwix/chrome/locale directory and the *.xul and/or *.js files you have modified.
After checking everything is OK, you can commit your modifications: ie. the kiwix/chrome/locale directory and the *.xul and/or *.js files you have modified.
</translate>


== Update Kiwix translations ==
<translate>== Update Kiwix translations == <!--T:24-->
</translate>


One other task is to update already supported Kiwix languages with the last string updated coming from Translatewiki. The first thing to know about that is that in the remote subversion repository, the Translatewiki file (in maintenance/translatewiki) are each two weeks updated from a Translatewiki contributors. That means, you only need to update your local repository and update and commit the kiwix code translation files like following:
<translate><!--T:25-->
Another task is to update already supported Kiwix languages with the last strings updated coming from Translatewiki. The first thing to know about that is that in the remote subversion repository, the Translatewiki file (in maintenance/translatewiki) is updated every two weeks from a Translatewiki contributors. That means, you only need to update your local repository and update and commit the kiwix code translation files like this:
</translate>


<source lang="bash">
<source lang="bash">
cd /full/path/to/the/kiwix/maintenance_tools/translatewiki
cd /full/path/to/the/kiwix/maintenance_tools/translatewiki
./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw
./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw
svn commit /full/path/to/the/kiwix/code/directory/kiwix/chrome/locale
git commit /full/path/to/the/kiwix/code/directory/kiwix/chrome/locale
git push origin master
</source>
</source>
<translate><!--T:26-->
The full path should be the moulinkiwix directory, not the kiwix directory in it.
The full path should be the moulinkiwix directory, not the kiwix directory in it.
</translate>


== Add a new supported language to Kiwix ==
<translate>== Add a new supported language to Kiwix == <!--T:27-->
</translate>


Kiwix tries to add only 100% translated languages coming from Translatewiki. So it happens often that they are more languages in the "maintenance_tools/translatewiki" directory than in the "kiwix/kiwix/chrome/locale" directory. In such a case, that simply mean the the Translatewiki language was still not integrated in Kiwix code base. We explain now how to do that.
<translate><!--T:28-->
Kiwix tries to add only 100% translated languages coming from Translatewiki. So it happens often that there are more languages in the "maintenance_tools/translatewiki" directory than in the "kiwix/kiwix/chrome/locale" directory. In such a case, that simply means the Translatewiki language was still not integrated in Kiwix code base. We explain now how to do that.
</translate>


First of all you need to create the translation files in a new directory at "kiwix/kiwix/chrome/locale/your_language_iso_code" like following:
<translate><!--T:29-->
First of all you need to create the translation files in a new directory at "kiwix/kiwix/chrome/locale/your_language_iso_code" like this:
</translate>


<source lang="bash">
<source lang="bash">
Line 90: Line 141:
</source>
</source>


After that you need go to the kiwix source code directory in "kiwix/chrome" and edit with your prefered text editor the "chrome.manifest" and "chrome.manifest.prod" files. No explanation here, just do like for the already supported languages.
<translate><!--T:30-->
After that, you need go to the Kiwix source code directory in "kiwix/chrome" and edit with your preferred text editor the "chrome.manifest" and "chrome.manifest.prod" files. No explanation here, just do like for the already supported languages.
</translate>


<translate><!--T:31-->
Next edit chrome/content/main/js/languages.js and here also add the new languages.
Next edit chrome/content/main/js/languages.js and here also add the new languages.
</translate>


<translate><!--T:32-->
Now update CHANGELOG and make a notice about the addition of the new supported languages.
Now update CHANGELOG and make a notice about the addition of the new supported languages.
</translate>
<translate><!--T:33-->
Add the new language directory and commit like this:
</translate>


Add the new language directory and commit like following:
<source lang="bash">
<source lang="bash">
svn add kiwix/chrome/locale/language_iso_code
git add kiwix/chrome/locale/language_iso_code
svn commit CHANGELOG kiwix/chrome/chrome.manifest kiwix/chrome/chrome.manifest.prod kiwix/chrome/locale/ kiwix/chrome/content/main/js/gui.js
git commit CHANGELOG kiwix/chrome/chrome.manifest kiwix/chrome/chrome.manifest.prod kiwix/chrome/locale/ kiwix/chrome/content/main/js/gui.js
git push origin master
</source>
</source>


== See also ==
<translate>== See also == <!--T:34-->
* [[Translation]]
* [[{{ll|Translation}}|Translation]]
* [[Compilation]]
* [[{{ll|Compilation}}|Compilation]]
</translate>


<translate><!--T:35-->
[[Category:Developer's Guide]]
[[Category:Developer's Guide]]
</translate>

Latest revision as of 21:03, 4 February 2015

Other languages:
Bahasa Melayu • ‎English • ‎català • ‎español • ‎français • ‎galego • ‎italiano • ‎magyar • ‎português • ‎русский • ‎日本語

Beside the pure translation part of the work, the Kiwix source code needs to be synchronized with Translatewiki.

This synchronization with Translatewiki needs three types of operations:

  • Add a string to Kiwix and Translatewiki, ie. introducing a dynamic string which will be replaced by the corresponding translation at the runtime.
  • Update the Kiwix strings with the translations coming from Translatewiki.
  • Add a new Translatewiki full translated language to Kiwix.

Requirements

You need a GNU/Linux Operating System. It is possible to do it in another operating system, but it is more complicated to get a working environment.

You need to have a few things in mind:

  • Kiwix translation files are all in the "kiwix/chrome/locale" directory.
  • There are two types of translation files to translate the User Interface (Have a look at the *.js and *.xul files in kiwix/chrome/content/main to understand how it works):
    • "main.dtd" which provides translations for all *.xul files
    • "main.properties" which provides translations for all *.js files.
  • Translatewiki translations are imported separately in the Kiwix code repository once a week and we always need to synchronize those files with Kiwix code in both directions (KW->TW and TW -> KW).

WARNING: Before any modification of Kiwix source code, update your local code repositories with "git pull origin master" in each one of them.

Checkout the code and start Kiwix

Before starting to work on the integration of new strings in the Kiwix code, it's preferable to achieve to compile Kiwix:

  • Get the unstable code
  • Compile it
  • Run it by going to the kiwix subdirectory and launching kiwix.

Remark: If you are not able to compile Kiwix, or do not have xulrunner available (is the case for example on Ubuntu Oneiric and further) you will still be able to start kiwix and get an interface although the application won't work correctly, but that's enough for example to manipulate the XUL files. In this case you will have to make a few additional steps like add "MaxVersion=42.*" as new line to kiwix/application.ini and launch Kiwix using this command in the "kiwix" directory "firefox -app application.ini".

Add a string to the translations

Find a string to localize

Go through the *.xul and *.js files to find hardcoded strings (in English).

If you find one you need to find a string identifier (foobar for example), have a look to the already localized string to see how it should look like. The most important to know is that in the *.xul files, it should look like "&foobar;" and in the *.js like "getProperty('foobar')".

Translate it in the master language English

You will need to do that on two places. First in the "kiwix/chrome/locale/en/main/" main.dtd or main.properties files. In that way the Kiwix application knows what to display if the user interface language is English.

Update Translatewiki files

But you also need to tell Translatewiki to add this string in the list of string it has to provide (for the Translatewiki translators) to translate. For that you need to checkout another part of Kiwix code repository. Please run outside of your local kiwix code directory following console command:

git pull origin master

You have now on your computer the translatewiki translations. What you need is only to update the "en" file which is the master language file for Translatewiki. So simply add your new string following the examples of other already inserted strings and commit your "en" file.

Someone from Translatewiki check each week the "en" file for new strings and synchronized Translatewiki with this file if necessary.

Create stub translation of you new string for all languages

The last thing you need to do is creating stub translation of your new localized string for all supported user interface languages in Kiwix. If you don't do that, Kiwix won't be able to work correctly in a language other than English.

For that purpose you need to use the TW2PL.pl script (this is a perl script, so perl needs to be installed) like following (go in the translatewiki file directory):

./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw

Commit the new Kiwix translation files

Now, all the locale file in kiwix/chrome/locale should be updated and you should have a lot of (modified) files listed by typing:

git status kiwix/chrome/locale

After checking everything is OK, you can commit your modifications: ie. the kiwix/chrome/locale directory and the *.xul and/or *.js files you have modified.

Update Kiwix translations

Another task is to update already supported Kiwix languages with the last strings updated coming from Translatewiki. The first thing to know about that is that in the remote subversion repository, the Translatewiki file (in maintenance/translatewiki) is updated every two weeks from a Translatewiki contributors. That means, you only need to update your local repository and update and commit the kiwix code translation files like this:

cd /full/path/to/the/kiwix/maintenance_tools/translatewiki
./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw
git commit /full/path/to/the/kiwix/code/directory/kiwix/chrome/locale
git push origin master

The full path should be the moulinkiwix directory, not the kiwix directory in it.

Add a new supported language to Kiwix

Kiwix tries to add only 100% translated languages coming from Translatewiki. So it happens often that there are more languages in the "maintenance_tools/translatewiki" directory than in the "kiwix/kiwix/chrome/locale" directory. In such a case, that simply means the Translatewiki language was still not integrated in Kiwix code base. We explain now how to do that.

First of all you need to create the translation files in a new directory at "kiwix/kiwix/chrome/locale/your_language_iso_code" like this:

./TW2KW.pl --path=/full/path/to/your/kiwix/code/base/directory/ --language=your_language_iso_code

After that, you need go to the Kiwix source code directory in "kiwix/chrome" and edit with your preferred text editor the "chrome.manifest" and "chrome.manifest.prod" files. No explanation here, just do like for the already supported languages.

Next edit chrome/content/main/js/languages.js and here also add the new languages.

Now update CHANGELOG and make a notice about the addition of the new supported languages.

Add the new language directory and commit like this:

git add kiwix/chrome/locale/language_iso_code
git commit CHANGELOG kiwix/chrome/chrome.manifest kiwix/chrome/chrome.manifest.prod kiwix/chrome/locale/ kiwix/chrome/content/main/js/gui.js
git push origin master

See also