Internationalisation
Size: 8073
Comment:
|
Size: 16015
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 4: | Line 4: |
'''THIS IS CURRENTLY A DRAFT''' |
|
Line 7: | Line 9: |
* how Ubuntu deals with translations (and i18n in general) | * how Ubuntu deals with translations (and i18n in general) from a developer's perspective |
Line 9: | Line 11: |
== General information == Be sure to read TranslationLifecycle in the [[TranslatingUbuntu|translations wiki pages]] for a general overview of how translations work in Ubuntu. |
|
Line 14: | Line 20: |
Note: once a package is promoted to `main`, it only needs to be rebuilt the first time after promotion so that [[https://launchpad.net/ubuntu/+source/pkgbinarymangler|pkgbinarymangler]] can strip the translations. After this, import to Launchpad Translations and export in language packs "will just happen". |
|
Line 112: | Line 120: |
* For GNOME packages: |
|
Line 114: | Line 125: |
''If there's more than one `./po/` directory (or it has a different name), please make sure to adjust it.'' | ''If there's more than one `./po/` directory (or it has a different name), please make sure to adjust the call above.'' * For KDE packages: TODO * For GNU packages: TODO: check {{{ make update-po}}} === Verifying translation uploads === This information is intended to help package maintainers to optimize their packages, so that translation related files get automatically imported into Launchpad. To test if your package conforms to the requirements of the import script in Launchpad, please do the following: 1. install the 'pkgbinarymangler' package 2. in /etc/pkgbinarymangler/striptranslations.conf set 'enable:' to "true" 3. optionally install any build dependencies: sudo apt-get build-dep $PKGNAME 4. build your package with 'debuild -uc -us -b' 5. You will find a '-translations.tar.gz' tarball along with the .deb package(s) 6. untar that tarball into a temporary directory 7. compare if the directory structure and the .pot and .po files conform to the requirements listed below 0. Glossary: * translation domain (domain) The application requires translations to be in /usr/share/locale/$LOCALE/LC_MESSAGES/ or /usr/share/locale-langpack/$LOCALE/LC_MESSAGES/ when they are shipped in our language-packs. The filename is $TRANSLATION_DOMAIN.po . For example: the application 'nautilus' may expect its translations to use the translation domain 'nautilus'. Therefor the filename would be 'nautilus.mo'. The corresonding translation template should have the same translation domain in its filename, e.g. 'nautilus.pot'. The expected translation domain name can only be found in the source code of the application. The translation domain must be unique across all applications and packages. I.e. something generic like 'messages.pot' won't work. If the application uses gettext, like most GTK and GNU applications do: * the filename of the .pot file should be the same as what the expected translation domain is. * the actual translations (.po files) must have a filename of the format $LANGUAGECODE.po or $LOCALECODE.po (e.g. de.po, pt_BR.po, zh_TW.po) * translation related files (.pot and the corresponding .po files) must end up in the same (sub-)directory. * if the application has multiple translation domains (i.e. multiple .pot files), each .pot file and their corresponding .po files should end up in a separate subdirectory (e.g. po/nautilus/nautilus.pot and po/libnautilus/libnautilus.pot) * templates and translations for the main application or library should go into po/. * templates and translations for help files should go into help/po/. They will be ignored by Launchpad, since we currently have no infrastructure to deal with them properly. * templates and translations for documentation files should go into doc/po/. They will also be ignored by Launchpad for the same reason as the help translations. * if there are .po files present but no associated .pot template, remove them. They are useless without a .pot template. There might be a bug in the package or in the source code that the .pot file doesn't get generated. * Please check if the .pot file has any meaningful content. Empty .pot files should be removed and the package build rules being fixed. * if your package contains patches and those patches result into extra templates, like 'patches.pot', please merge those changes into the main template, as we have no use for patch .pot files. Such .pot files should not exist in the final tarball. * If the package generates multiple .pot files and later merges them into one, only the final .pot file should be present in the final tarball. The other ones are useless. * If the package creates the same .pot file in architecture dependent subdirectories, please consider to merge them, as we can only deal with one single .pot per translation domain. * test routines and test files should not generate any .pot template or ship any .po file. If such files are present, please remove them. == Desktop Entries == Translations of [[http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec|desktop entries]] (.desktop files) are also stripped out and included in language packs. This is done by adding the '''X-Ubuntu-Gettext-Domain''' [[http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s08.html|additional key]]. As an example for this key in action, here's how it is done in the Transmission source package in Jaunty (from the `20_add_X-Ubuntu-Gettext-Domain.diff` patch): {{{ Index: transmission-1.40-2ubuntu1/gtk/transmission.desktop.in =================================================================== --- transmission-1.40-2ubuntu1.orig/gtk/transmission.desktop.in 2008-12-09 18:57:13.000000000 +0000 +++ transmission-1.40-2ubuntu1/gtk/transmission.desktop.in 2008-12-09 18:58:54.000000000 +0000 @@ -9,3 +9,4 @@ Type=Application MimeType=application/x-bittorrent; Categories=Network;FileTransfer;P2P;GTK; +X-Ubuntu-Gettext-Domain=transmission }}} In summary, for packages in `main` we strip the translations out of the .desktop files, and gnome-panel (TODO: is this the right package?, TODO: how is this done in KDE?) has a patch to load a translation from the .mo file. It basically uses that key to figure out where to get the translation from. The preferred way to implement this is either through `debian/patches` or by using the [[http://packages.ubuntu.com/search?searchon=contents&keywords=langpack.mk&mode=exactfilename&suite=jaunty&arch=any|langpack.mk]] rule if the package uses CDBS. * [[LangpacksDesktopfiles|Original specification]] * [[LangpacksDesktopfilesKDE|Original specification for KDE]] == Documentation == === GNOME docs === === KDE docs === === K/Ubuntu docs === * See also DocumentationTeam/Translation === Xubuntu docs === Note: ''the Xubuntu docs have now moved to universe'' == The import queue == All translation templates (.pot files) and translations (.po) end up in the Launchpad Translations import queue before being imported into Launchpad. Some of the Ubuntu import queues: * [[https://translations.launchpad.net/ubuntu/hardy/+imports?field.filter_extension=pot&field.filter_status=NEEDS_REVIEW|Hardy]] * [[https://translations.launchpad.net/ubuntu/intrepid/+imports?field.filter_extension=pot&field.filter_status=NEEDS_REVIEW|Intrepid]] * [[https://translations.launchpad.net/ubuntu/jaunty/+imports?field.filter_extension=pot&field.filter_status=NEEDS_REVIEW|Jaunty]] * [[https://translations.launchpad.net/ubuntu/karmic/+imports?field.filter_extension=pot&field.filter_status=NEEDS_REVIEW|Karmic]] Templates generally get approved automatically, but sometimes there is some manual work involved in approving them. The [[https://launchpad.net/~ubuntu-translation-coordinator|Ubuntu Translations Coordinators Team]] manages the import queue. We've got a [[ubuntu-translation-coordinator@lists.launchpad.net|mailing list]] where issues can be discussed and we welcome the help of any community members experienced with translations. |
Line 118: | Line 226: |
* For GNOME packages: |
|
Line 122: | Line 232: |
Note: ''this is only worth trying if the package uses intltool for i18n (i.e. look for intltool.m4 in the top-level source directory)'' * For GNU packages: * For KDE packages: |
|
Line 124: | Line 240: |
== Kubuntu-specific notes == == Additional notes on packages not using the Gettext format == === Mozilla === === OpenOffice.org === |
Getting Started |
THIS IS CURRENTLY A DRAFT
Translations in Ubuntu (from a developer perspective)
This page tries to outline
- how Ubuntu deals with translations (and i18n in general) from a developer's perspective
- which tools are interesting for developers to make sure that translations and i18n work fine
General information
Be sure to read TranslationLifecycle in the translations wiki pages for a general overview of how translations work in Ubuntu.
Language Packs
General
Packages in main and restricted don't contain translations (*.mo) files themselves, they are stripped during the build on the Launchpad buildds and put into language-pack-* packages instead. This is done in an attempt to bundle the translations you're interested in and cut down the occupied space.
Note: once a package is promoted to main, it only needs to be rebuilt the first time after promotion so that pkgbinarymangler can strip the translations. After this, import to Launchpad Translations and export in language packs "will just happen".
Comparing the contents of a package built by Launchpad Soyuz and a locally built one:
daniel@bert:~$ debdiff --nocontrol gcalctool_5.27.2-0ubuntu1_amd64.deb /var/cache/pbuilder/result/gcalctool_5.27.2-0ubuntu1_amd64.deb [The following lists of changes regard files as different if they have different names, permissions or owners.] Files in second .deb but not in first ------------------------------------- -rw-r--r-- root/root /usr/share/locale/af/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/am/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ar/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/as/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ast/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/az/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/be/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/be@latin/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/bg/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/bn/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/bn_IN/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/bs/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ca/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ca@valencia/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/cs/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/cy/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/da/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/de/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/dz/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/el/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/en_CA/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/en_GB/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/en_US/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/es/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/et/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/eu/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/fa/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/fi/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/fr/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ga/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/gl/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/gu/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/he/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/hi/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/hr/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/hu/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/id/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/it/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ja/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ka/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/kn/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ko/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ku/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/lt/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/lv/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/mai/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/mg/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/mk/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ml/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/mn/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/mr/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ms/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/nb/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ne/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/nl/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/nn/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/oc/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/or/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/pa/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/pl/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/pt/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/pt_BR/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ro/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ru/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/rw/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/si/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sk/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sl/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sq/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sr/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sr@latin/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/sv/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/ta/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/te/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/th/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/tk/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/tr/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/uk/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/vi/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/xh/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/zh_CN/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/zh_HK/LC_MESSAGES/gcalctool.mo -rw-r--r-- root/root /usr/share/locale/zh_TW/LC_MESSAGES/gcalctool.mo daniel@bert:~$
Translations Templates
For pkgstriptranslations (in the pkgbinarymangler package) to do the job right, please make sure that your package in main or restricted builds a .pot during the build. It does not necessarily need to be shipped in the source or in the binary package. Generating it during the build is good enough. This can be achieved by running the following in debian/rules:
- For GNOME packages:
cd po; intltool-update -p
If there's more than one ./po/ directory (or it has a different name), please make sure to adjust the call above.
- For KDE packages:
TODO
- For GNU packages:
TODO: check
make update-po
Verifying translation uploads
This information is intended to help package maintainers to optimize their packages, so that translation related files get automatically imported into Launchpad.
To test if your package conforms to the requirements of the import script in Launchpad, please do the following:
- install the 'pkgbinarymangler' package
- in /etc/pkgbinarymangler/striptranslations.conf set 'enable:' to "true"
- optionally install any build dependencies: sudo apt-get build-dep $PKGNAME
- build your package with 'debuild -uc -us -b'
- You will find a '-translations.tar.gz' tarball along with the .deb package(s)
- untar that tarball into a temporary directory
- compare if the directory structure and the .pot and .po files conform to the requirements listed below
0. Glossary:
- translation domain (domain)
- The application requires translations to be in /usr/share/locale/$LOCALE/LC_MESSAGES/ or /usr/share/locale-langpack/$LOCALE/LC_MESSAGES/ when they are shipped in our language-packs. The filename is $TRANSLATION_DOMAIN.po . For example: the application 'nautilus' may expect its translations to use the translation domain 'nautilus'. Therefor the filename would be 'nautilus.mo'. The corresonding translation template should have the same translation domain in its filename, e.g. 'nautilus.pot'. The expected translation domain name can only be found in the source code of the application. The translation domain must be unique across all applications and packages. I.e. something generic like 'messages.pot' won't work.
If the application uses gettext, like most GTK and GNU applications do:
- the filename of the .pot file should be the same as what the expected translation domain is.
- the actual translations (.po files) must have a filename of the format $LANGUAGECODE.po or $LOCALECODE.po (e.g. de.po, pt_BR.po, zh_TW.po)
- translation related files (.pot and the corresponding .po files) must end up in the same (sub-)directory.
- if the application has multiple translation domains (i.e. multiple .pot files), each .pot file and their corresponding .po files should end up in a separate subdirectory (e.g. po/nautilus/nautilus.pot and po/libnautilus/libnautilus.pot)
- templates and translations for the main application or library should go into po/.
- templates and translations for help files should go into help/po/. They will be ignored by Launchpad, since we currently have no infrastructure to deal with them properly.
- templates and translations for documentation files should go into doc/po/. They will also be ignored by Launchpad for the same reason as the help translations.
- if there are .po files present but no associated .pot template, remove them. They are useless without a .pot template. There might be a bug in the package or in the source code that the .pot file doesn't get generated.
- Please check if the .pot file has any meaningful content. Empty .pot files should be removed and the package build rules being fixed.
- if your package contains patches and those patches result into extra templates, like 'patches.pot', please merge those changes into the main template, as we have no use for patch .pot files. Such .pot files should not exist in the final tarball.
- If the package generates multiple .pot files and later merges them into one, only the final .pot file should be present in the final tarball. The other ones are useless.
- If the package creates the same .pot file in architecture dependent subdirectories, please consider to merge them, as we can only deal with one single .pot per translation domain.
- test routines and test files should not generate any .pot template or ship any .po file. If such files are present, please remove them.
Desktop Entries
Translations of desktop entries (.desktop files) are also stripped out and included in language packs.
This is done by adding the X-Ubuntu-Gettext-Domain additional key. As an example for this key in action, here's how it is done in the Transmission source package in Jaunty (from the 20_add_X-Ubuntu-Gettext-Domain.diff patch):
Index: transmission-1.40-2ubuntu1/gtk/transmission.desktop.in =================================================================== --- transmission-1.40-2ubuntu1.orig/gtk/transmission.desktop.in 2008-12-09 18:57:13.000000000 +0000 +++ transmission-1.40-2ubuntu1/gtk/transmission.desktop.in 2008-12-09 18:58:54.000000000 +0000 @@ -9,3 +9,4 @@ Type=Application MimeType=application/x-bittorrent; Categories=Network;FileTransfer;P2P;GTK; +X-Ubuntu-Gettext-Domain=transmission
In summary, for packages in main we strip the translations out of the .desktop files, and gnome-panel (TODO: is this the right package?, TODO: how is this done in KDE?) has a patch to load a translation from the .mo file. It basically uses that key to figure out where to get the translation from.
The preferred way to implement this is either through debian/patches or by using the langpack.mk rule if the package uses CDBS.
Documentation
GNOME docs
KDE docs
K/Ubuntu docs
- See also DocumentationTeam/Translation
Xubuntu docs
Note: the Xubuntu docs have now moved to universe
The import queue
All translation templates (.pot files) and translations (.po) end up in the Launchpad Translations import queue before being imported into Launchpad.
Some of the Ubuntu import queues:
Templates generally get approved automatically, but sometimes there is some manual work involved in approving them. The Ubuntu Translations Coordinators Team manages the import queue. We've got a mailing list where issues can be discussed and we welcome the help of any community members experienced with translations.
General Advice
If you want to make sure that your packages translations are set up correctly, try running:
- For GNOME packages:
cd po; intltool-update -m
and be sure to either fix the issues or report them upstream.
Note: this is only worth trying if the package uses intltool for i18n (i.e. look for intltool.m4 in the top-level source directory)
- For GNU packages:
- For KDE packages:
Sometimes empty .po files caused packages to build from source.
Kubuntu-specific notes
Additional notes on packages not using the Gettext format
Mozilla
OpenOffice.org
UbuntuDevelopment/Internationalisation (last edited 2010-08-18 14:21:17 by 140)