<!-- <chapter id="translators-level5"><title>Translating &d-i; - Level 5</title> -->

<sect1 id="translators-level5">
<title>
Level 5
</title>

<sect2 id="level5_contents">
<title>

Contents
</title>

<para>
All packages which have been, at some moment, aprt of &d-i;
translation levels, are no more used directly during the install
process, but are considered important enough for being translated are
part of level 5 of &d-i; localization.
</para>

<para>This includes the following Debian packages:

	    <itemizedlist>
	      <listitem>
		<para>
		  debconf (debconf)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  debconf (program)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  shadow (program)
		</para>
	      </listitem>
	    <listitem>
	      <para>
		newt
	      </para>
	    </listitem>
	      <listitem>
		<para>
		  aptitude
		</para>
	      </listitem>
	      <listitem>
		<para>
		  console-common
		</para>
	      </listitem>
	      <listitem>
		<para>
		  dictionaries-common
		</para>
	      </listitem>
	      <listitem>
		<para>
		  dpkg
		</para>
	      </listitem>
	      <listitem>
		<para>
		  apt
		</para>
	      </listitem>
	    </itemizedlist>
</para>

<para>
<classname>dpkg</classname> and <classname>apt</classname> are very often used during the
whole life of a Debian system, so having them translated, though very
tedious, is a must-have for a good localized system.
</para>

</sect2>

<sect2 id="level5_debconf">
<title>
Debconf
</title>

<sect3 id="level5_debconf_description">
<title>
Package description
</title>

<para>
The <classname>debconf</classname> Debian package is the program which
handles all configuration steps of other packages when these packages
need some user interaction while they are configured.
</para>

<para>
This package is installed on all Debian systems. Its installation
process usually inputs the user about the default priority of
questions. However, when installed in a normal &d-i; installation
process, these answers are pre-filled with the priority settings of
the installation process. As a consequence, the questions are usually
hidden from users.
</para>

<para>
However, as the package is a <quote>key</quote> Debian package, its
translation is important for a properly localized system.
</para>

</sect3>

<sect3 id="level5_debconf_files">
<title>
Files location and access methods
</title>

<para>
The package uses a <acronym>SVN</acronym> repository. Commit access may be requested to
the &i18n-coords;. However, as the translatable parts do not change
very often, getting commit access is not highly useful.
</para>

<itemizedlist>
<listitem>
Anonymous <acronym>SVN</acronym> access: <command>&svn-debconf;</command>
<para>
The debconf translation lies in the <filename>debian/po</filename> directory, while the programs translation is in <filename>po/</filename>.
</para>
</listitem>
<listitem>
<para>
<acronym>HTTP</acronym> access: 
</para>
<itemizedlist>
<listitem>
<para>
          <ulink url="&url-level5-pot;/debconf_debian_po.pot">&url-level5-pot;/debconf_debian_po.pot</ulink>
</para>
</listitem>
<listitem>
<para>
&url-level5-po;/debconf_debian_po_&language;.po
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>

</sect3>


<sect3 id="level5_debconf_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>debconf</classname> package.
</para>

</sect3>

<sect3 id="level5_debconf_recommendations">
<title>
Specific recommendations
</title>

<para>
The translations are very similar to the questions asked by the
<classname>cdebconf</classname> package, which is part of the level1
of &d-i; translations.
</para>

<para>
Translators should then be careful about using the same terminology in
both packages, especially for questions priorities. This can be done
by merging the translations from &d-i; level1 into
<classname>debconf</classname> translations.
</para>

</sect3>

</sect2>

<sect2 id="level5_debconfp">
<title>
debconf (program)
</title>

<sect3 id="level5_debconfp_description">
<title>
Package description
</title>

<para>
The <command>debconf</command> program is the software which is used
for user interaction during Debian packages configuration step. All
Debian packages should use <command>debconf</command> when they need
user input for installation-time configuration.
</para>

<para>
<command>debconf</command> may output information to the screen: this
is why the program translation is included in &d-i; fourth level of
translation.
</para>

<para>
<classname>Debconf</classname> also prompts users with questions when
installed. However, during a complete &d-i; run, these questions are
pre-answered with the similar questions from the
<classname>cdebconf</classname> package (which is part of level 1). As
a consequence, the translation of these questions is only part of level
5.
</para>

</sect3>

<sect3 id="level5_debconfp_files">
<title>
Files location and access methods
</title>

<para>
The package uses a <acronym>SVN</acronym> repository. Commit access may be requested to
the &i18n-coords;. However, as the translatable parts do not change
very often, getting commit access is not highly useful.
</para>

<itemizedlist>
<listitem>
Anonymous <acronym>SVN</acronym> access: <command>&svn-debconf;</command>
<para>
The debconf translation lies in the <filename>debian/po</filename> directory, while the programs translation is in <filename>po/</filename>.
</para>
</listitem>
<listitem>
<para>
<acronym>HTTP</acronym> access: 
</para>
<itemizedlist>
<listitem>
<para>
          <ulink url="&url-level5-pot;/debconf_po.pot">&url-level5-pot;/debconf_po.pot</ulink>
</para>
</listitem>
<listitem>
<para>
&url-level5-po;/debconf_po_&language;.po
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_debconfp_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the <classname>debconf</classname> package or committed directly to the <acronym>SVN</acronym> repository.
</para>

</sect3>

<sect3 id="level5_debconfp_recommendations">
<title>
Specific recommendations
</title>

<para>
N/A
</para>

</sect3>

</sect2>

<sect2 id="level5_shadow">
<title>
Shadow
</title>

<sect3 id="level5_shadow_description">
<title>
Package description
</title>

<para>
The utilities installed by this package have been internationalized
and, as they are core utilities for a Debian system, translating them
is important to achieve a good localization of the installed system.
</para>

<para>This translation is, like <classname>apt</classname> and
<classname>dpkg</classname> translations, a
<emphasis>program</emphasis> translation: programs (like
<filename>passwd</filename>, <filename>chpw</filename>,
<filename>chsh</filename>, etc.) output, error and help messages. Such
translation is quite tedious and long term work and need some
carefulness (respect line breaks, variable substitutions...).
</para>

</sect3>

<sect3 id="level5_shadow_files">
<title>
Files location and access methods
</title>

<para>
</para>

<para>
This package is a <quote>regular</quote> Debian package. Programs
translations are maintained by the upstream maintainer who
uses a <acronym>CVS</acronym> repository.
</para>

<itemizedlist>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/shadow_po.pot">&url-level5-pot;/shadow_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/shadow_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_shadow_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>shadow</classname> package. The upstream maintainer will
pick them from there.
</para>

</sect3>

<sect3 id="level5_shadow_recommendations">
<title>
Specific recommendations
</title>

<para>
Upstream has a monthly release schedule with usually one week string freeze before each release. Call for updates will be sent during this string freeze.
</para>

<para>
Uploads of the Debian package will occur one or two weeks after upstream has released his new version.
</para>

</sect3>

</sect2>

<sect2 id="level5_newt">
<title>
Newt
</title>

<sect3 id="level5_newt_description">
<title>
Package description
</title>

<para>
The newt package is a library (whiptail) which includes widgets used by
the most popular interface to the debconf software, the software
involved in packages configuration steps. These widgets include the <guibutton>Yes</guibutton> or  <guibutton>No</guibutton> widgets used by boolean templates, as well as the  <guibutton>OK</guibutton> or  <guibutton>Abort</guibutton> buttons
text.
</para>

</sect3>

<sect3 id="level5_newt_files">
<title>
Files location and access methods
</title>

<para>
No public revision control repository is available for this package so access through the translation statistics pages is the only way to get translation material for it:
</para>

<itemizedlist>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/newt_po.pot">&url-level5-pot;/newt_newt_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/newt_newt_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_newt_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the <classname>newt</classname> package.
</para>

</sect3>

<sect3 id="level5_newt_recommendations">
<title>
Specific recommendations
</title>

<para>
N/A
</para>

</sect3>

</sect2>

<sect2 id="level5_aptitude">
<title>
aptitude
</title>

<sect3 id="level5_aptitude_description">
<title>
Package description
</title>

<para>
The <classname>aptitude</classname> program is an combination of
interactive and non-interactive tools for installing Debian
packages. For long-time users of Debian, it may be seen as the
replacement for both <command>dselect</command> and
<command>apt-get</command>.
</para>

<para>The program uses a text-based menu system when used interactively and
includes a lot of output messages when it is run non-interactively.
</para>

<para>
<classname>aptitude</classname>'s full translation is a huge work
because there are hundreds of strings in the POT file. Moreover, this
requires some good knowledge of several Debian package managements
concepts. It is recommended that this translation is handled by an
experienced Debian system administrator.
</para>

</sect3>

<sect3 id="level5_aptitude_files">
<title>
Files location and access methods
</title>

<para>
This package is a <quote>regular</quote> Debian package. The
package maintainer uses a <acronym>Mercurial</acronym> repository for the program development
(the Debian package is handled in a separate <acronym>Mercurial</acronym> repository).
</para>

<itemizedlist>
  <listitem>
    <para>
      Anonymous <acronym>Mercurial</acronym> access: <command>&hg-aptitude;</command>
    </para>
  </listitem>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/aptitude_po.pot">&url-level5-pot;/aptitude_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/aptitude_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_aptitude_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>aptitude</classname> package.
</para>

</sect3>

<sect3 id="level5_aptitude_recommendations">
<title>
Specific recommendations
</title>

<para>Without any doubt, <classname>aptitude</classname>'s translation
is among the most difficult translations involved in &d-i;
translation. It has an impact far outside &d-i; because
<classname>aptitude</classname> is likely to be used all along the
life of a Debian system.
</para>

<para>
Several strings in <classname>aptitude</classname> PO file are menu
entries, pseudo dialog boxes text and all such limited size
material. The source code is not very widely commented to help out
translators.
</para>

<para>
The ideal way to translate aptitude is by recompiling the software and
include the translation to be tested. Compiling aptitude requires
usual build tools and software as well as a few dedicated libraries
such as <classname>apt</classname> libraries.
</para>

<para><classname>Aptitude</classname> also includes a small help file, which may be
translated as well. However, this translation does not use GNU
gettext, so the translation is quite tricky. See the
<filename>help*</filename> files in <classname>aptitude</classname>'s source tree.
</para>

<para><classname>Aptitude</classname>'s documentation may also be
translated. See the <filename>doc/</filename> directory in the
package's source tree.
</para>

<para>Translators should be aware that <classname>aptitude</classname>
is still under heavy development, so upstream strings are very likely
to change or be added. Anyway, even a partial translation will help the
users of a given language.
</para>

<para>

The aptitude maintainer has written a special
<filename>README.i18n</filename> file to give more details to
translators. The contents of this file follows, as of the day of this
documentation was written.
</para>

<para>
<classname>Aptitude</classname> uses the standard gettext mechanism for translations.  However,
there are a few twists that you should be aware of.
</para>

<sect4 id="level5_aptitude_recommendations_external">
<title>
External data files
</title>

<para>
    There are several external data files that you can choose to
    translate: <filename>help.txt</filename> (online help), <filename>help-mine.txt</filename> (online help for
    Minesweeper), and <filename>aptitude.xml</filename> (user's manual/online manual).
    <filename>aptitude.xml</filename> is a large file, but <filename>help.txt</filename> and <filename>help-mine.txt</filename> are
    quite tractable and it is recommended that you translate
    them. (especially <filename>help.txt</filename>)
</para>

<para>
    aptitude applies gettext to the file names before loading them, so
    to tell it that you've translated (eg) <filename>help.txt</filename> to <filename>help-de.txt</filename>,
    you should add a translation "help.txt" -> "help-de.txt".
</para>

<para>
    In addition, each translated file name has a corresponding
    described translation (see below) indicating its encoding.  You
    should translate this as necessary if you write an alternate file.
</para>
</sect4>

<sect4 id="level5_aptitude_recommendations_manpage">
<title>Manpage</title>

<para>
    <classname>aptitude</classname> has a manpage, and it can be translated; if you choose to
    translate it, your translation should be named <filename>aptitude.XX.1</filename>
    (replace XX with the language code)
</para>

</sect4>
<sect4>
<title>fragf</title>

<para>
    <classname>aptitude</classname> uses an internal function called fragf to format text
    with display attributes.  This function works somewhat like
    printf, but most escape codes have different meanings.  For
    instance, %B enables the "bold" character attribute, while %b
    disables it.  See src/vscreen/fragment.h for a full description of
    all escape codes.  You can use parameter numbers (eg, %1$F) if
    your language needs to reorder the arguments.
</para>

</sect4>

<sect4 id="level5_aptitude_recommendations_keys">
<title>Key translations</title>

<para>
    Where it makes sense, <classname>aptitude</classname> allows the default keybinding
    assigned to a command to be translated.  This is done by creating
    a dummy translated string ending in "_key"; the first character of
    the string is the default binding of the key.  For instance, the
    string "yes_key" is used to set the default binding for buttons
    labelled "Yes".  To bind "j" to this command, you could translate
    "yes_key" to "ja_key", "ja", or even just "j".
</para>

</sect4>
<sect4 id="level5_aptitude_recommendations_described">
<title>Described translations</title>

<para>
    Some translations have descriptions or disambiguating text to the
    left of the input and output string.  In these cases, everything
    up to and including the first pipe character will be removed
    before the string is used.  If no pipe character is present in the
    string, the string will be used without modifications.

    For instance, the string "help.txt encoding|UTF-8" can be
    translated to either "help.txt encoding|ISO-8859-1",
    "|ISO-8859-1", or "ISO-8859-1", and will have the same effect in
    each case.
</para>
</sect4>


</sect3>

</sect2>

<sect2 id="level5_console">
<title>
Console-common
</title>

<sect3 id="level5_console_description">
<title>
Package description
</title>

<para>
The <classname>console-common</classname> package includes all tools
for handling the console (input and output).
</para>

<para>
It is installed and configured as part of the Debian base system. Its
configuration process involves some user input and may be shown to
users during a base system install, in some occasions (but not
always).
</para>

</sect3>

<sect3 id="level5_console_files">
<title>
Files location and access methods
</title>

<para>
</para>

<itemizedlist>
  <listitem>
      <acronym>SVN</acronym> access: <command>&svn-console-common;</command>
  </listitem>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/console-common_debian_po.pot">&url-level5-pot;/console-common_debian_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/console-common_debian_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_console_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>console-common</classname> package.
</para>

</sect3>

<sect3 id="level5_console_recommendations">
<title>
Specific recommendations
</title>

<para>
N/A
</para>

</sect3>

</sect2>

<sect2 id="level5_dictionaries">
<title>
dictionaries-common
</title>

<sect3 id="level5_dictionaries_description">
<title>
Package description
</title>

<para>
The <classname>dictionaries-common</classname> package includes all
common tools for using word dictionaries in Debian.
</para>

<para>
It is installed and configured as part of the Debian base system. Its
configuration process inputs the user for choosing a word dictionary
when the installation is run at <emphasis>medium</emphasis> priority (using the <emphasis>expert</emphasis>
mode of install...or when some problem occurred earlier in the
installation process).
</para>

</sect3>

<sect3 id="level5_dictionaries_files">
<title>
Files location and access methods
</title>

<para>
This package is a <quote>regular</quote> Debian package. The
package maintenance team uses a <acronym>CVS</acronym> repository.
</para>

<itemizedlist>
  <listitem>
Anonymous <acronym>CVS</acronym> access: <command>&cvs-dictionaries-common;</command>
  </listitem>
<listitem>
<para>
<acronym>HTTP</acronym> access: 
</para>
<itemizedlist>
<listitem>
<para>
          <ulink url="&url-level5-pot;/dictionaries-common_debian_po.pot">&url-level5-pot;/dictionaries-common_debian_po.pot</ulink>
</para>
</listitem>
<listitem>
<para>
&url-level5-po;/dictionaries-common_debian_po_&language;.po
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_dictionaries_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the <classname>dictionaries-common</classname> package.
</para>

</sect3>

<sect3 id="level5_dictionaries_recommendations">
<title>
Specific recommendations
</title>

<para>
N/A
</para>

</sect3>

</sect2>

<sect2 id="level5_dpkg">
<title>
dpkg
</title>

<sect3 id="level5_dpkg_description">
<title>
Package description
</title>

<para>
The <classname>dpkg</classname> program is a low level program which
installs and removes Debian packages.
</para>

<para>Including it in &d-i; level 4 of translation is an extension of
the scope of &d-i; localization process. <classname>dpkg</classname>
does not output very often during a base system install, but is very
likely to be used further, either directly invoked by the system
administrator or from another program such as
<classname>aptitude</classname>, <classname>apt</classname>, or <classname>dselect</classname>
(<classname>dselect</classname> translations are part of
<classname>dpkg</classname> translations).
</para>

<para><classname>dpkg</classname> full translation is a huge work
because there are hundreds of strings in the POT file. Most of these
strings are very short strings and most of them are hard-formatted
because they are used from a command-line program.
</para>

</sect3>

<sect3 id="level5_dpkg_files">
<title>
Files location and access methods
</title>

<para>
This package is a <quote>regular</quote> Debian package. The
package maintenance team uses GIT to maintain
it. 
</para>

<itemizedlist>
<listitem>
<acronym>GIT</acronym> access: &git-dpkg; (Some documentation:<ulink url="&git-dpkg-doc;">&git-dpkg-doc;</ulink>)
</listitem>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/dpkg_po.pot">&url-level5-pot;/dpkg_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/dpkg_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_dpkg_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>dpkg</classname> package or commited directly to the GIT repository (in such case, please read maintainers' instructions at <command>&git-dpkg;</command>). Don't forget updating the <classname>po/Changelog</classname> and <classname>debian/changelog</classname> files if you update the translations yourself via GIT.

</para>

<para>
If reported as a bug, the translation will be committed quickly by the dpkg localization
maintainer.
</para>

</sect3>

<sect3 id="level5_dpkg_recommendations">
<title>
Specific recommendations
</title>

<para>
Undoubtfully, <classname>dpkg</classname> translation
requires a good knowledge of the Debian package management system as
well as some good experience of command-line programs translation.
</para>

<para>
The developers have put comments targeted at translators for some
strings. Translators should read and follow them carefully.
</para>

<para>
The <classname>po/</classname> directory contains a file named <classname>Changelog</classname>. Translators must update this file when updating translations, as well as the <classname>debian/changelog</classname> file.
</para>

<para>
Adding a new language also requires translators to add it to the
<classname>po/LINGUAS</classname> file. Otherwise, the new translation
will not be used.
</para>

<para>
<classname>dpkg</classname> man pages can also be translated, using
gettext files. Please look into the <classname>man/</classname>
directory in GIT for examples.
</para>

</sect3>

</sect2>

<sect2 id="level5_apt">
<title>
apt
</title>

<sect3 id="level5_apt_description">
<title>
Package description
</title>

<para>
The <classname>apt</classname> program handles installation and
removal of Debian packages from packages <emphasis>sources</emphasis>
such as Debian <acronym>HTTP</acronym>/FTP mirrors, Debian CD's, third party CD's or
repositories, or local files.
</para>

<para>
Including it in &d-i; level 4 of translation is an extension of the
scope of &d-i; localization process. <classname>apt</classname> does not output
very often during a base system install, but is very likely to be used
further.
</para>

</sect3>

<sect3 id="level5_apt_files">
<title>
Files location and access methods
</title>

<para>
This package is a <quote>regular</quote> Debian package. The
package maintenance team uses arch repositories to maintain
it. 
</para>

<para>
As arch-style repositories are somewhat complicated to setup, all
localization of <classname>apt</classname> is handled by one of the
&i18n-coords;.
</para>

<itemizedlist>
  <listitem>
    <para>
      <acronym>HTTP</acronym> access: 
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="&url-level5-pot;/apt_po.pot">&url-level5-pot;/apt_po.pot</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          &url-level5-po;/apt_po_&language;.po
        </para>
      </listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

</sect3>

<sect3 id="level5_apt_updates">
<title>
Updating/Adding translations
</title>

<para>
Translations should be reported as bugs against the
<classname>apt</classname> package.
</para>

<para>
The translation will be committed quickly by the dpkg localization
maintainer. This will not appear immediately on status pages because
<classname>apt</classname> development is handled in
<quote>arch</quote> repositories which are not easily handled by the
scripts which generate the status pages.
</para>

</sect3>

<sect3 id="level5_apt_recommendations">
<title>
Specific recommendations
</title>

<para><classname>apt</classname> full translation is a huge work because there are hundreds of
strings in the POT file. Most of these strings are short strings
and most of them are hard-formatted because they are outputted
during the use of a command-line program.
</para>

<para>
Similarly to <classname>dpkg</classname>, <classname>apt</classname>
translation requires a good knowledge of the Debian package management
system as well as some good experience of command-line programs
translation.
</para>

<para>
The developers have put comments targeted at translators for some
strings. Translators should read them carefully. Some of them are
<emphasis>very</emphasis> important.
</para>

</sect3>

</sect2>

</sect1>

<!-- </chapter> -->
