Man Linux: Main Page and Category List

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.