EM_INSTALLTDEB(1) User Contributed Perl Documentation EM_INSTALLTDEB(1)
NAME
em_installtdeb - generate Emdebian TDeb translation packages and source.
SYNOPSIS
em_installtdeb
em_installtdeb [LANG_CODE]
em_installtdeb [--no-act]
em_installtdeb [--no-sign]
Copyright and Licence
Copyright (C) 2007-2008 Neil Williams <codehelp@debian.org>
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
DESCRIPTION
em_installtdeb is a debhelper add-on created by Emdebian to create translation packages (tdebs). em_installtdeb is intended to separate out
the individual translation files from the current Debian packages into packages without any translation files and a series of tdeb locale
packages, one per translation. Generated packages use the syntax: $package-locale-$language_code_$version_all.deb
(From v3.0.0 onwards, TDebs are architecture-independent.)
Once a package uses em_installtdeb, translation files should be removed from all packages in the normal build. em_installtdeb runs as a
second build (very small, very fast) that simply converts and packages the *.po files into tdebs. A tdeb source package is created (.dsc,
.tar.gz and .changes) alongside the existing build data. The source package is used by translators to build updated or new tdeb packages.
Tdeb .changes files need to be uploaded only to secondary locale repositories instead of the main Debian mirrors and these repositories can
have much more relaxed upload policies. Tdeb packages have no dependencies and no packages may depend upon them.
em_installtdeb currently only supports gettext translation.
Certain language codes need to be modified to make acceptable components of a debian package name. Underscores are converted to hyphens,
'@' is converted to '+' and all codes are made lowercase. These changes only apply to the package name, the installation location is
unchanged.
The locale package must use GETTEXT_PACKAGE for the eventual filename of the binary translation file - although this may be the same as the
$dh{MAINPACKAGE}. GETTEXT_PACKAGE is determined by upstream, not Debian. When building the whole package, the binary translation file may
be in debian/tmp/usr/share/locale/$lang/LC_MESSAGES but when in translator mode, this location is not available. Instead retrieve
GETTEXT_PACKAGE from the POT filename, the Makefile GETTEXT_PACKAGE macro or if that is not set, use the upstream source package name. This
may need extending.
The "source" for translators therefore includes:
debian/rules /* dummy file */
debian/control
debian/changelog
po*/$lang.po /* if any */
po*/$GETTEXT_PACKAGE.pot /* may be more than one */
Some packages use multiple po directories and em_installtdeb checks for a POT file in all usable po directories, including them in the tdeb
source along with all po files: e.g.
po/fr.po
po-lib/fr.po
po/application.pot
po-lib/library.pot
When packaged, the tdeb built from this source would contain:
./usr/share/locale/fr/LC_MESSAGES/application.mo
./usr/share/locale/fr/LC_MESSAGES/library.mo
An equivalent tdeb for the 'de' locale would contain:
./usr/share/locale/de/LC_MESSAGES/application.mo
./usr/share/locale/de/LC_MESSAGES/library.mo
This compares with the Debian "space-is-cheap" model of separating the application.mo and library.mo files but combining all the
translations in one package, so that the equivalent Debian package would contain:
./usr/share/locale/cs/LC_MESSAGES/application.mo
./usr/share/locale/de/LC_MESSAGES/application.mo
./usr/share/locale/fr/LC_MESSAGES/application.mo
...
./usr/share/locale/sv/LC_MESSAGES/application.mo
./usr/share/locale/ro/LC_MESSAGES/application.mo
./usr/share/locale/vi/LC_MESSAGES/application.mo
(Repeated again for the other package.)
Many packages contain dozens of translations - some contain over 70 .mo files and .mo files can vary between 2kb and 30kb each. Without
tdebs, all users get all 70 translations even if only one or two are used. With tdebs, all users get both the library and the application
translations but only for the one or two locales supported by that installation. The extra granularity achieved by splitting application.mo
and library.mo into separate packages for the same locale is not likely to be worth the workload. (In effect, this means that packages with
multiple translations are not actually supported - at least not in the original manner.) It is possible that developments like dpkg
filtering will be able to implement this final level of division, where necessary.
em_installtdeb will try to generate the necessary POT file(s) and then create a $package_$version_tdeb.tar.gz containing the source files.
Any package can have a source tdeb, as long as the POT file is either packaged or can be built. The package does not have to have been
translated already.
For more detail on Tdebs, see: <http://www.emdebian.org/emdebian/langupdate.html> <http://wiki.debian.org/i18n/TranslationDebs>
Note that the Emdebian implementation of tdebs differs from the proposed tdebs for Debian because Emdebian does not care about manpages in
general, let alone translated manpages. Once the 'nodocs' DEB_BUILD_OPTION is supported in debhelper, this will not be an issue as the
tdebs can be built for Emdebian without any manpages. Other translated documentation would be omitted under 'nodocs' too. Images
containing translated text are relatively few.
To manage the increase in package numbers (average ten fold), the secondary locale repository organises the tdeb packages by locale root,
e.g. 'en_GB' is beneath 'en' and 'sr@Latn' beneath 'sr'. Each locale root becomes a single apt source in the locale repository to support
fallback from a specific locale to a the more general locale root. In this manner, each device only has to cope with cache data for a
fraction of the total number of tdeb packages (roughly 1 part in 30).
A new C/C++ application then handles the installation and update of tdeb packages according to the list of supported locales and the list
of installed packages. Data cached by langupdate is temporary and is not intended to be stored between runs of langupdate.
OPTIONS
The default action is to process all available po files.
This mode is used by package maintainers to generate tdeb source and binaries at the end of the Debian build (with translation files
omitted). Note that this means a second .dsc, second .changes, a second (much smaller) .tar.gz using the tdeb.tar.gz suffix and a separate
upload to the secondary locale repositories. emdebian-tools will include handlers for these operations and Debian can create similar
wrappers as needed.
This single-language update mode of em_installtdeb is unlikely to be retained once dpkg-gentdeb is available because translations are less
likely to be updated within Emdebian than within Debian.
LANG_CODE
LANG_CODE can either be the name of the locale as specified in the PO filename (fr, en_GB, sr@Ltn etc.) or the name of the locale as
specified in the eventual package name (fr, en-gb, sr+ltn etc.).
If a po file already exists for this locale, em_installtdeb processes just that one translation and builds a single tdeb package.
If the po file does not exist, em_installtdeb exits with an error. (Copy the POT file from the original source to create a new po file
for the new locale and edit it to include the new translation, then run em_installtdeb again.)
LANG_CODE is intended as a 'translator mode' where individual tdeb packages can be built by the translator and uploaded to a suitable
repository. em_installtdeb creates the tdeb source tarball, a usable .dsc file to describe the tdeb source and a tdeb.changes file.
no-act
em_installtdeb will just print the control data that would be used for the tdeb if the debhelper --no-act option is used.
no-sign
em_installtdeb normally calls 'debsign' when the .changes is written. This option suppresses this behaviour.
Use in Debian
Note that the use of debian/xcontrol in the current script means that XS-TDeb-Build-Directory and XS-TDeb-POT-Names will need to be
supported in debian/control before adoption by Debian. At the same time, XC-Package-Type: tdeb needs support too.
reprepro needs a patch to accept .tdeb and allow .tdeb in the repository files:
$ reprepro --ignore=extension -b /path/ includedeb
unstable ../qof-locale-sv_0.7.5-1em1_arm.tdeb
$ ls /opt/reprepro/locale/pool/main/q/qof/
qof-locale-sv_0.7.5-1em1_arm.deb
Filename: pool/main/q/qof/qof-locale-sv_0.7.5-1em1_all.deb
Description: sv translation for qof (tdeb)
reprepro also needs a way to handle a .tdeb .changes file.
reprepro -b /opt/reprepro/locale/ include unstable ../qof_0.7.5-1em1_arm.changes
'qof-locale-id_0.7.5-1em1_arm.tdeb' is not .deb or .udeb!
There have been errors!
For the debian/rules file in the generated source package to be useful, em_installtdeb needs to be split up so that dpkg-buildpackage gets
the right data to create a usable .changes file because em_installtdeb is too good at cleaning up after itself.
endianness
Until version 3.0.0, Emdebian packages used architecture-dependent TDebs but this proved to be unnecessary, TDebs are now architecture-
independent, using the internal gettext wrapper.
Other translations
Packages may also contain translated manpages and translations for debconf templates. These translations are not packaged or processed by
em_installtdeb because Emdebian does not need to handle such files and because each variant will need customised handling (most of the
debconf support is already available). If Tdebs are to be supported in Debian, these issues will need to be resolved such that Emdebian can
continue to only package the gettext program translations, omitting translated manpages and leaving debconf translation support to existing
tools.
Use of debhelper::init
The problem with init is that $dh{DOPACKAGES} works from debian/control and the locale packages are not *in* debian/control. So
em_installtdeb gets the "Source: " package name to use as the prefix for the locale package names.
Translator mode
This is a special mode, not usually something that debhelper would do. In translator mode, debian/rules is not used. em_installtdeb does
everything needed to configure, build, install and package the requested tdeb and the appropriate tdeb source package using a temporary
directory to ensure that the correct control and changelog data is available.
There are a few issues with this method - the build needs a debian/changelog but also needs to create the translation as a native package
(to prevent the need for an empty .diff.gz) even if the upstream package is non-native. The current solution is to create a new version
(with tdeb appended) to create a clean changelog entry that does not try to re-close bugs from the original upload and then use that
version to force dpkg-source to treat the tdeb source as a native package. This may need changing in future but such changes are likely to
need support in dpkg. This method, whilst not ideal, does work with the existing support. Using a modified version also ensures that the
generated files do not interfere with other builds in the same location. Although not used, a basic debian/rules file is added.
if DEBSIGN_KEYID is defined, em_installtdeb tries to use debsign to sign the .tdeb.changes and .dsc files. This could be made optional if
it is later decided that translation uploads will need full changelog entries to close bugs in the Debian BTS. Part of the appeal of tdebs
is that i18n bugs would not normally need to be filed in the BTS.
perl v5.12.3 2011-06-18 EM_INSTALLTDEB(1)