path: root/english/international/l10n/ddtp.wml

#use wml::debian::template title="The Debian Description Translation Project — DDTP"
#use wml::debian::toc

<p>
The <a href="https://ddtp.debian.org">Debian Description Translation Project</a>
(which was implemented by
<a href="mailto:Michael%20Bramer%20%3Cgrisu@debian.org%3E">Michael Bramer</a>)
aims to provide translated
package descriptions and the infrastructure to support their translation. Even
though it exists already for a few years it was deactivated after a break-in
of a
Debian host and has currently only basic functionality compared to the past.
</p>

<p>
The project supports:
</p>
<ul>
  <li>Fetching of current (sid) and older package descriptions.</li>
  <li>Reusing of already translated paragraphs from one description in other
      package descriptions.</li>
  <li>Providing of <tt>Translation-*</tt> files for mirrors and APT.</li>
</ul>

<p>
The
non-free section in the Debian archive is not translatable at the moment
because there could exist license
<!-- I thought that even for non-free projects the debian packaging stuff
     (debian/) is free but it seems it''s not required!? -->
issues which forbid e.g. translation and need to be checked carefully.
</p>

<p>
Translating more than 56000 package transcriptions is a big challenge. Please
help us to fulfill our goal. See also our <a href="#todo">todo</a> list for
remaining issues.
</p>

<toc-display/>

<toc-add-entry>Interfaces to the DDTP</toc-add-entry>

<p>
Since all interfaces use the DDTP backend, you first need to ensure that your
language is already supported. This should be the case for most
languages. If there does not exist such support write to
<email debian-i18n@lists.debian.org>

so that your language can be activated.
</p>

<h3 id="DDTSS">The web frontend</h3>
<p>
A nice web frontend exists
called <a href="https://ddtp.debian.org/ddtss/index.cgi/xx">DDTSS</a> written by
<a href="mailto:Martijn%20van%20Oosterhout%20%3Ckleptog@gmail.com%3E">Martijn van
Oosterhout</a> which tries to simplify the task of translation and review.
</p>

<h4>Overview</h4>
<p>
It supports contributing translations and additionally allows
proofreading. It supports a custom configuration for each language team so that
each team can decide how many reviews are necessary until the description
is transferred to the DDTP. It's also possible to request user authorisation,
so that only a restricted group of people can perform certain actions. You also don't
have to care about the encoding, the DDTSS handles this for you.
</p>

<p>
Current default properties:
</p>
<dl>
  <dt>number of reviews:</dt><dd>3</dd>
  <dt>supported languages:</dt><dd>all of the DDTP</dd>
  <dt>user authorisation:</dt><dd>no, it's open for all</dd>
</dl>

<p>
It is possible to specify a default word list for a language. This is used to
provide default translations via tooltips. This list is available via a link
at the bottom of the language page.
</p>

<h4>Workflow</h4>
<p>
The DDTSS provides the following items for all languages:
</p>

<h5>Pending translation</h5>
<p>
A list of pending translations. These are descriptions freely selectable for
translation by the user. It looks like:
</p>
<pre>
exim4 (priority 52)
exim4-config (priority 52)
ibrazilian (priority 47, busy)
postgresql-client (priority 47)
postgresql-contrib (priority 47)
grap (priority 45)
</pre>

<p>
A language team should try to translate packages with a high priority (this is
calculated using the category, e.g. essential, base, ...) first. The packages
are sorted to accomplish this.
</p>

<p>
Descriptions marked with busy are already reserved by a user and cannot be
selected for at most 15 minutes. If there is no commit during this time it's again
marked as freely available.
</p>

<p>
A description needs to be completely translated before the frontend accepts it.
So please ensure that you are able to translate the entire text before
you start. Select <q>Submit</q> to add your translation and <q>Abandon</q>
if you decide not to translate it. It's also possible that you are lucky and that
there is already a translation for a previous version of the English template 
together with a diff of the changes in the English translation which you have
to integrate into your translation.
You could copy and paste this old translation from the bottom part of the page
and update it appropriately.
</p>

<p>
# Does not yet work as expected
To avoid ugly fluctuation of the text width it is suggested that you do not
enter newlines manually unless necessary (such as for list items). The lines
break automatically. Remember that an user could add or remove minor parts
during proofreading which could otherwise result in an inconsistent line
length. Fixing this too makes the diff created by the review hard to read.
</p>

<p>
It's also possible to select preferred packages by name. This is useful to
translate a set of similar packages, such as manpages-de, manpages-es, in order
and to be able to copy and paste previous translations.
</p>

<p>
Even already translated packages can be fetched this way again, to improve them
(please note that the current DDTP functionality for this is buggy, so please
avoid it if possible for now).
</p>

<h5>Pending review</h5>
<p>
A list of translated descriptions which still need to be reviewed. This list
might look like the following:
</p>

<pre>
 1. aspell-es (needs review, had 1)
 2. bookmarks (needs initial review)
 3. doc-linux-ja-html (needs initial review)
 4. doc-linux-ja-text (needs initial review)
 5. gnome-menus (needs initial review)
 6. geany (needs review, had 2)
 7. initramfs-tools (needs initial review)
 8. inn2 (needs initial review)
</pre>

<p>
The following flags exist:</p>
<dl>
    <dt lang="en">needs initial review:</dt>
    <dd>The current version of this translation has not
        yet passed a single review.</dd>

    <dt lang="en">needs review:</dt>
    <dd>The current version of this translation needs further
        reviews, but passed already at least one.</dd>

    <dt lang="en">reviewed:</dt>
    <dd>This description was reviewed without change by the user.
        Other users needs to proofread it.</dd>

    <dt lang="en">owner:</dt>
    <dd>This description was translated or changed during a proofread by the
        user. Other users needs to proofread it.</dd>
</dl>

<p>
If a review with corrections has already happened you will get a nice color
diff which shows all changes of the last review once you select the package.
</p>

<h5>Recently translated</h5>
<p>
A list of transferred description to the DDTP. At most twenty packages together
with the date of the transfer are listed.
</p>

<h3 id="Pootle">The internationalisation frontend</h3>
<p>
There have been plans to implement a new framework to aid translation of various
documents in Debian, such as PO files and Debconf templates. This should also
support package descriptions at some time. If this becomes active and works as
expected, the current DDTP and it's frontends would be shut down.
</p>

<p>
This framework would be based on
<a href="http://pootle.locamotion.org/">Pootle</a>. It was a Google Summer of
Code <a href="https://wiki.debian.org/SummerOfCode2006?#Translation_Coordination_System">project</a>.
</p>

<toc-add-entry name="rules">Common translation rules</toc-add-entry>
<p>
It's important that you do not change English descriptions during translation.
If you recognise errors in them you should file a bug report against the
corresponding package, see <a href="$(HOME)/Bugs/Reporting">How to report a bug
in Debian</a> for details.
</p>

<p>
Translate the untranslated parts of each attachment which are marked
&lt;trans&gt;. It's important that you do not change lines containing only a
period in the first column. These are paragraph separators and will not be
visible in APT frontends.
</p>

<p>
Paragraphs which are already translated are either reused from other descriptions
or from an older translation (and thus indicate that this original English
paragraph was not changed since that time). Once you change such a paragraph, it
will not change all other descriptions with the same paragraph as well.
</p>

<p>
Also note that each language team has it's own preferences such as word lists
or quotation style. Please follow these standards as close as possible. The
# Translators: create a link to your rules from "published"
most important rules are published. It is suggested that you start reviewing
existing translations, either via <a href="#DDTSS">DDTSS</a> or by browsing
descriptions in package management systems such as
<a href="https://packages.debian.org/aptitude">aptitude</a>, first to get a
# Translators: create a link to your language team (mailing list, ...)
feeling for the translation preferences. If you are unsure contact your language team.
</p>

<toc-add-entry>Proofreading and error fixing</toc-add-entry>
# General proofread suggestions, not DDTSS specific
<p>
Only the DDTSS currently implements a review mode and only sends those
translations to the DDTP which passed a fixed number of proofreads.
</p>

<p>
Once you notice common typos or other easy to correct errors such as encoding
problems, it is possible to bypass any review process and to fix this for all
packages at once using a script. It is suggested that only one trusted
translation coordinator collects all these issues and applies the script.
</p>

<p>
Since the proofreading can take a long time (especially if only
minor issues are fixed all the time), it may be an option to just ignore
simple typos and inconsistencies during the review and to start a check
for all of these (hopefully collected) issues later. This speeds up the review and
allows to apply these corrections later in all descriptions.
</p>

<toc-add-entry>Usage of the translations</toc-add-entry>
<p>
Proper support for translated package descriptions is available since the APT
package in
<a href="https://packages.debian.org/lenny/admin/apt">lenny</a>.
Using this package every user can read the
descriptions in his preferred language in all programs which use APT.  This
includes <tt>apt-cache</tt>, <tt>aptitude</tt>, <tt>synaptic</tt>, and various
other.
</p>

<p>
APT downloads <tt>Translation-<var>lang</var></tt> files from
Debian mirrors. These are only available for lenny and newer distributions.
The location of these files on mirrors is
# Translators: use a proper mirror!
<a href="http://ftp.debian.org/debian/dists/sid/main/i18n/">dists/main/sid/i18n/</a>.
</p>

<p>
It's also possible to disable usage of translations. To achieve this just add
</p>
<pre>
APT::Acquire::Translation "none";
</pre>
<p>
to <tt>/etc/apt/apt.conf</tt>. Instead of <tt>none</tt> also a language code
is supported.
</p>

<!--
<p>
FIXME: I need to test this script from me again against the new Translation-<lang>
files. Ignore this for now:<br />
There is also a small script available which just replaces English descriptions
in the local <tt>Packages</tt> files (<tt>/var/lib/apt/lists/</tt>) with
translations. This could be used if the new APT version cannot be installed for
whatever reasons.
</p>
-->

<toc-add-entry name="todo">Todo</toc-add-entry>

<p>
Even though there is some progress for the DDTP there is still a lot to do:
</p>
<ul>
  <li>All translation teams currently search new translators and reviewers
      which help to process the really large package list.</li>
  <li>Add support for improving English package descriptions during the
      translation/review process. Maybe this could be archived by adding a
      new English pseudo language containing the improved description as
      translation and automatic filing of a bug after a successful review.</li>
  <li>The new internationalisation framework based on Pootle needs a lot of
      work until it fulfills all of our ideas.</li>
</ul>