NAME
em_installtdeb - generate Emdebian TDeb translation packages and
source.
SYNOPSIS
em_installtdeb
em_installtdeb -a|--arch ARCHITECTURE
em_installtdeb [LANG_CODE]
em_installtdeb [-a|--arch ARCHITECTURE] [--no-act]
em_installtdeb [-a|--arch ARCHITECTURE] [--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_$arch.deb
(Note that TDebs are architecture-dependent.)
Unlike other cross building related tools, em_installtdeb does NOT read
your default dpkg-cross architecture. This is because it also needs to
be usable for native builds. When crossbuilding, ensure you explicitly
set the -a|--arch option. (emdebuild does this for you.)
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_arm.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
A limited number of architectures are handled internally by
em_installtdeb. The list of supported archictures can be extended by
installing dpkg-cross and adding the configuration for the extra
architectures.
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.