Development/en
Few infos for the developers...
Contents |
Get the code
You can download the code of kiwix from our Subversion repository:
- Unstable version (actual)
svn co https://kiwix.svn.sourceforge.net/svnroot/kiwix/moulinkiwix/ moulinkiwix
- Stable version (old)
svn co https://kiwix.svn.sourceforge.net/svnroot/kiwix/branches/kiwix-0.8/ moulinkiwix
You can in addition browse the code:
http://svn.kiwix.orgYou might also want to use Git or Mercurial as client, please follow the guidelines here:
git svn clone -Tmoulinkiwix -ttags -bbranches https://kiwix.svn.sourceforge.net/svnroot/kiwix git svn rebase # update, and base your change on the new version git svn dcommit # commit
To have a git mirror of kiwix, use the following commands:
git svn clone https://kiwix.svn.sourceforge.net/svnroot/kiwix git remote add origin git@github.com:kiwix/kiwix.git git svn rebase # update from svn git push origin master # push it into git mirror
Compile it
The compilation is standard.
Please follow these steps:
./autogen.sh ./configure make
On Fedora, the compilation is a little bit more complicated. You have to:
./autogen.sh ./configure --with-xpidl=/usr/lib/xulrunner-`pkg-config --modversion libxul`/ --with-gecko-idl=/usr/lib/xulrunner-sdk-`pkg-config --modversion libxul`/sdk/idl make
Translation the GUI
This page explains how to add/update string translations in Kiwix. String translations are done one Translatewiki which is a powerful software translation online platform.
So, if you want to translate Kiwix strings in your language:
- go on http://www.translatewiki.net,
- choose your mother language,
- request the translator permissions,
- translate the strings of Kiwix which still need to be translated.
But this is one of the tasks related to Kiwix localization. Kiwix itself, that means the source code, needs to be synchronized with Translatewiki. To achieve to do that, they are basically three additional operations:
- Add a string, that means transforming a hard coded string in the source code in a dynamic string which will replaced by the corresponding translation in the end user language.
- Update the Kiwix translations in subversion with the Translatewiki ones
- Add a new Translatewiki full translated language to Kiwix
Prerequisites
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 still need to remember a few things:
- Kiwix translation files are all in the "kiwix/chrome/locale" directory.
- They are two types of translation files to translate the User Interface:
- the main.dtd which provides translations for all *.xul files and
- main.properties which provides translations for all *.js files. Have a look to the js and xul file in kiwix/chrome/content/main to understand how it works.
- Translatewiki translations are imported separately in the Kiwix subversion code repository and we always need to synchronize thus files with kiwix code.
Before any modification of Kiwix source code, update your local code repository with "svn update".
Add a string to the translations
Checkout the code and start Kiwix
To find a hard-coded string, you need to get the development version of the code, compile it and run it :
- Get the unstable code like explained here.
- Compile it like explained here
- 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 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".
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 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 it in the master language English
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.
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 an other part of Kiwix subversion repository. Please run outside of your local kiwix code directory following console command:
svn co https://kiwix.svn.sourceforge.net/svnroot/kiwix/maintenance_tools/translatewiki
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 two weeks 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 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.
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):
./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 update and you should have a lot of (modified) files listed by typing:
svn status kiwix/chrome/locale
After checking everything is alright, you can commit your modifications: ie. the kiwix/chrome/locale directory and the *.xul and/or *.js files you have modified.
Update Kiwix translations
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:
cd /full/path/to/the/kiwix/maintenance_tools/translatewiki ./TW2KW.pl --path=/full/path/to/the/kiwix/code/directory --allLanguages=kw svn commit /full/path/to/the/kiwix/code/directory/kiwix/chrome/locale
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 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.
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:
./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 prefered 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 following:
svn 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
See also
</noinclude>
