Generate DoudouLinux in another language

DoudouLinux is built using a LiveCD creation tool as explained in the page How to generate a CD/USB image. The tool, named live-helper, reads configuration files in a given directory and then builds the LiveCD/LiveUSB image. These configuration files tell the tool what language to use, what keyboard layout to use, what software packages to install, etc. To provide full customization it is even possible to overwrite any file before the LiveCD/LiveUSB image file is produced. This feature is also used to translate several texts.

As we want to be able to build DoudouLinux for many different languages, configuration files are not modified directly in the standard live-helper directory. Instead we have a base configuration directory config-base/ and a localization one config-l10n/. The base directory is supposed to be language-agnostic as the localization one hosts language specific customization only. To ease the generation of a new language, DoudouLinux provides a helper script init-lang.sh that generates a new language configuration set.

Finally applications may also need to be translated (or better translated). Configuration files as seen set only the DoudouLinux environment. If you want to translate texts in some applications, you have to produce internationalization files. These files can then be integrated to localization directories or used to patch the application and generate a new Debian package. The easier is the first solution!

Notes:

• If you just intend to provide us (by email) translated text files of any already existing DoudouLinux CDROM, you should not need to read the 2nd section “Adding a new language” and the 6th one “Language package lists”. Packages of translation files can be downloaded at page Translation files, they are also online at TransiFex.
• If you don’t want to bother with the entire Live system generation, you can ask us to put on our server a “raw” version of DoudouLinux for your language (just tell us your full language code and the keyboard layout please). Once the Live image is available, we can provide you with the necessary files for translations and integrate them back to DoudouLinux once your translation job is done.
• Use UTF-8 character encoding for all your texts! (but not for boot menu).
• User documentation is fetched from this web site with dedicated tools, so documentation translation relies on the website software Spip.

1- Understanding the config-l10n/ tree

The localization directory contains the following tree:

config-l10n/
├── apps/	= SVN externals coming from lang/trunk/apps/
├── desktop-entries/	= SVN externals coming from lang/trunk/env/icons/
├── overwrite/
│   ├── ar/
│   ├── en/
│   ├── es/
│   ├── fr/
│   ├── …
├── packagelists/
└── rewrite/
    ├── settings/
    └── templates/

As you can see, the tree is made of:

• apps/, an SVN mirror of application translation files from the SVN branch lang/trunk/apps/
• desktop-entries/, an SVN mirror of icon files and categories (LxLauncher tabs) from the SVN branch lang/trunk/env/icons/
• overwrite/, for files that will overwrite some other files, they are arranged by language using two-letter code directories (fr/, es/, etc.)
• packagelists/, for language-specific package lists (dictionaries, etc.)
• rewrite/, for scripts that rewrite some base configuration files

Please note that apps/ and desktop-entries/ only appears when you fetch the SVN code onto your computer because they are only externals [1]. All these directories and files are explained in this document. To better understand why there are so many directories, it is necessary to explain how the LiveCD/LiveUSB build process starts:

1. base configuration files are copied from config-base/ into build/config/
2. language-specific files are copied from config-l10n/overwrite/xx/ into build/config/
3. files of application icons and categories are copied from config-l10n/desktop-entries/ into sub-directories of build/config/chroot_local-includes/
4. rewrite scripts from rewrite/ are run to translate some texts directly from within build/config/

After these operations, the actual configuration directory build/config/ is ready and LiveCD/LiveUSB creation can be launched using live-helper.

2- Adding a new language

To create a new translation, you need to create:

• the language setting file config-l10n/rewrite/settings/xx
• the language package list file config-l10n/packagelists/doudoulinux-l10n-xx
• the language directory of files to be overwritten config-l10n/overwrite/xx/

A script init-lang.sh helps you creating all these files and directories. Just go into doudoulinux/live/trunk/ and type:

./init-lang.sh xx

where xx is the language two-letter code. Any previously existing file will not be modified nor deleted so that it can also be used to update language directories whenever needed. Note that you are not free to chose the two-letter code since Debian uses the ISO specification. See the FAQ developer page to find how to get these codes.

3- Application icons and LxLauncher tabs

Texts of applications icons and LxLauncher tabs are stored in *.directory and *.desktop files. These files are located in the “lang/” tree: lang/trunk/env/icons/applications/ and lang/trunk/env/icons/desktop-directories/. They are already multi-language and do not have to be duplicated but directly edited instead [2]. Please do not edit the SVN copy in live/trunk/config-l10n/desktop-entries/ except for testing purposes because you will not be able to commit your changes from this directory.

Contents of icon files or categories looks like this:

[Desktop Entry]
Type=Application
Version=1.0
Encoding=UTF-8
Name=SuperTux
GenericName=A Platform Game
GenericName[fr]=Un jeu de saut et course
GenericName[de]=Ein Jump&Run Spiel
GenericName[cs]=Plošinová hra
Comment=A Super Mario inspired penguin platform game
Comment[fr]=Un jeu de pingouin inspiré de Super Mario®
Comment[de]=Ein von Super Mario inspiriertes Pinguin Jump&Run Spiel
Comment[cs]=Plošinovka inspirovaná SuperMariem s tučňákem Tuxem v hlavní roli
Icon=supertux.png
Exec=supertux
Terminal=false
StartupNotify=false
Categories=Application;Game;ArcadeGame

You have to translate or improve at least Comment and eventually Name strings. Name is the application icon name as displayed on the DoudouLinux desktop. Comment is the description balloon which is displayed whenever the mouse passes above the application icon. Please feel free to add any missing Comment[xx] or Name[xx] entry for your language.

Note that reference texts for translations are English and French. Their meaning may differ from any already existing translation since we may have adapted texts to our audience: children. Note also that you may have to copy additional *.desktop files into lang/trunk/env/icons/applications/ if you find some other icons that would not be translated in your language or not correctly. Such files can be copied from /usr/share/applications/ or /usr/share/desktop-directories/ while running the LiveCD.

4- Rewrite directory

Rewrite script have been created to avoid duplication of configuration scripts just to change few texts from one to another. Instead a single template configuration file from config-base/ can be reused for each language. Rewrite scripts are modifying templates at runtime in the build/config/ directory. The rewrite directory contains rewriting libraries in its root and rewriting scripts identically named in language sub-folders. For example we currently have 4 scripts 90session-user in the tree config-l10n/rewrite/ plus the library script:

$ find config-l10n/rewrite/ -name 90session-user
config-l10n/rewrite/90session-user
config-l10n/rewrite/es/90session-user
config-l10n/rewrite/ar/90session-user
config-l10n/rewrite/fr/90session-user
config-l10n/rewrite/en/90session-user

Here the library is config-l10n/rewrite/90session-user. If you want to translate into Arabic, you need to change config-l10n/rewrite/ar/90session-user only. This makes it possible to modify the library without necessarily changing all the associated rewrite scripts which are language-specific.

NB: as rewrite process only operates before the LiveCD/LiveUSB is actually built, you cannot rewrite files that appear while installing packages. This means that rewrite scripts are essentially targeting configuration files. Bug fixes or boot modifications must operate using config-l10n/xx/ or build hooks, a feature of live-helper.

As of writing, rewrite scripts are the following:

rewrite script	what it changes
01binary	system language and keyboard layout
01bootstrap	Debian repository mirror (see http://www.debian.org/mirror/list to get a neighbor server)
01set-grub-syslinux	boot texts (Grub/Syslinux)
05translate-shutdown	very last text displayed in console before shutdown
10lxlauncher-session	logout dialog title
12lxpanel-lowbat	low battery dialog
20cups-pdf	PDF printer definition
90session-user	session menu entries (GDM)
92skel-profile	Telepathy Salut account

This may change in future DoudouLinux releases.

5- Configuration files

Directories config-l10n/xx/ contain configuration files that may overwrite files coming from config-base/. These directories are supposed to contain:

• files that are not modified or do not exist in another language
• files that cannot be generated during a live-helper build
• files that cannot be processed by rewrite scripts (binary files for instance)

As of writing, config-l10n/xx/ directories may contain the following files:

configuration file	what to change
chroot_local-includes/etc/localtime	computer local time
chroot_local-includes/etc/timezone	computer time zone
fr/chroot_local-includes/etc/skel/.vkeybdmap	vkeybd keymap, depends on keyboard layout
chroot_local-includes/etc/skel/poster-xx.png	DoudouLinux poster image

This may change in future DoudouLinux releases.

6- Language package lists

Each language must provide a list of localization packages named doudoulinux-l10n-xx in the directory config-l10n/packagelists/. This package list is automatically merged into the global package list file at runtime. Usually this file contains translation packages but it may happen that some applications are dedicated to very few languages (eg. French verbs, Spanish verbs, etc.).

Package list files are simple text files containing the package names. You can write several package names per line using a space separator. Comment character is the number sign “#”. For example:

# DoudouLinux localization file
#
# defines language specific packages

# dictionary / language
verbiste-gnome
dict-freedict-fra-eng dict-freedict-eng-fra
dict-freedict-fra-deu dict-freedict-deu-fra
dict-freedict-fra-nld dict-freedict-nld-fra
apertium-tolk apertium-fr-es 

# kid games
gcompris-sound-fr
childsplay-alphabet-sounds-fr childsplay-lfc-names-fr

etc.

Packages specific to a given language can be found with the command “apt-cache search”:

$ apt-cache search freedict english | cut -d ’ ’ -f 1

It is also possible to use TAB completion on this type of command:

$ dpkg -l childsplay-lfc-names-<press TAB>
childsplay-lfc-names-ca  childsplay-lfc-names-fr  childsplay-lfc-names-nl

7- DoudouLinux packages

DoudouLinux is also developing few (small) applications. As we have full access to their source code and their Debian repository, we prefer updating these packages instead of putting files into config-l10n/ [3]. The files to be modified are located in the tree packages/trunk/apps/. If you need to find some *.desktop files, you can issue the following:

$ find packages/trunk/apps/ -name ’*.desktop’
packages/trunk/apps/vkeybd-timidity/source/vkeybd-timidity.desktop
packages/trunk/apps/live-persistence/source/share/applications/persistence-gui.desktop
packages/trunk/apps/doudou-mouse/source/share/applications/mouse-settings.desktop
packages/trunk/apps/doudou-sound/source/share/applications/set-alsa-output.desktop

If you need to find a translation file to be modified because texts in the interface are wrong or untranslated, use this:

$ find packages/trunk/apps/ -name ’*.po’
apps/liveusb-write/source/share/locale/fr/LC_MESSAGES/liveusb-write.po
apps/live-persistence/source/share/locale/fr/LC_MESSAGES/live-persistence.po
apps/doudoulinux-mouse/source/share/locale/fr/LC_MESSAGES/doudoulinux-mouse.po
apps/doudoulinux-sound/source/share/locale/fr/LC_MESSAGES/doudoulinux-sound.po

PO files are just text files but can be edited with dedicated graphical tools such as PoEdit. Finally if you want to make a new “*.po” file from scratch, you may use the helper script ./init-lang.sh from the doudoulinux/packages/trunk/ directory:

$ ./init-lang.sh xx packagename

where xx is your language two letter code and packagename the name of the application. This command will also update the translation file template, the POT file. You can then use this to update a particular translation file when application (English) texts have changed [4]. To find these template files, type the following:

$ find packages/trunk/apps/ -name ’*.pot’
apps/liveusb-write/source/lib/liveusb-write/messages.pot
apps/live-persistence/source/lib/live-persistence/messages.pot
apps/doudoulinux-mouse/source/lib/doudoulinux-mouse/messages.pot
apps/doudoulinux-sound/source/lib/doudoulinux-sound/messages.pot

8- Patched packages

DoudouLinux also hosts some patched Debian packages. Similarly to DoudouLinux packages, it is better to modify the patched applications and then produce a new patch. But if you do not want to bother with patching application, just have a look at [an article coming soon…].

9- How to test modified packages

The simplest way to test a package change is to write a DoudouLinux USB key with full persistence activated, not only user data persistence. While running DoudouLinux, you are able to change anything and these changes are automatically recorded onto the USB key. If you don’t know which file is to be modified in a given package, use a command similar to the following one:

$ dpkg -L supertuxkart | grep ’.desktop$’
/usr/share/applications/supertuxkart.desktop

The command dpkg -L just lists all the installed package files. Please note that PO files are compiled into MO files in order to speedup translation text lookup. Compiling is achieved using most of dedicated graphical tools.

Another way to proceed is to copy the modified files into the corresponding sub-directory of config-base/chroot_local-includes/ or config-l10n/xx/chroot_local-includes/ and then rebuild the entire CD/USB key image. Finally the last way consists in rebuilding the modified package (*.deb file) then move it into the live/trunk/localpackages/ directory.

Once your changes are satisfying, just send them to us please!