NOTES FOR TRANSLATORS
=====================

Introduction
------------

The dgit source package builds several binary packages:
dgit, git-debrebase, git-debpush, and dgit-infrastructure.
These are useful for a variety of different users and in different
situations.  So there are various documents aimed at various users.

* dgit and git-debrebase both support message translation.

* Documentation translation is handled via po4a, in the po4a
  directory.  The documeents are all manpages.

* git-debrebase is currently mostly useful within the Debian project.

The en_US message translation is slightly special.  It is used for
testing the translation machinery, and since the source native
language is en_GB, there is not much other need for the en_US
translation.

The threshold for generation of a translated documents has been set to
10% (of each individual document).  The documents are quite sectional
and I expect even a partially translated document to be useful.


Translatation priorities
------------------------

  HIGH

    po4a/dgit-user_7.pot    How to use dgit to as a downstream or user

  MEDIUM

    po/messages.pot         All the messages for all programs

    po4a/dgit_1
    po4a/dgit-downstream-dsc_7
    po4a/dgit-sponshorship_7
    po4a/dgit_7
    po4a/git-deborig_1

  LOW - For work within Debian, where one needs good English anyway:

    po4a/dgit-maint-*
    po4a/dgit-nmu-simple_7
    po4a/git-debpush_1
    po4a/git-debrebase_*
    po4a/tag2upload_5


Translation organisation
------------------------

  po/messages.pot      all messages from both dgit and git-debrebase
  po/LANG.po           translations of those
  po/mo                output directory, do not look here

  po4a/MAN_S.pot       paragraphs from manpage MAN in section S
  po4a/MAN_S.LANG.po   translation of manpage MAN(S) into LANG
  po4a/po4a.cfg        config file for po4a
  po4a/LANG.preview    preview for you, see below
  po4a/translated/     output directory, do not look here


Note on git-debrebase
---------------------

git-debrebase has a fairly complex underlying model, which is defined
in git-debrebase(5).

It is importnt when translating both documents and messages for
git-derebase, that consistent translations are used for the words
defined in `TERMINOLOGY' and `BRANCH CONTENTS'.

You may want to start by reading git-debrebase(5).

When translating git-debrebaase(5) itself, please add the English term
after the defining use of each word.  For example
   Your-word-for-pseudomerge (Pseudomerge)
       translation of the definition
This will be useful because some of these words appear in
necessarily-untranslated but user-visible protocol elements
(eg sometimes in annotations in autogenerated git commit messages)


To start translating
--------------------

In po/

  1. run
      make LANGUAGE.po
  2. edit LANGUAGE.po to add translations.

In po4a/

  1. edit po4a.cfg to add your language to [po4a_langs]
  2. then run
     po4a po4a.cfg
  3. edit each MANPAGE_SECTION.LANG.po to add translations.


Important commands for translators
----------------------------------

In po/

  make LANGUAGE.po     Creates or updates messages.pot and LANGUAGE.po.

  make pofiles         Updates messages.pot from all the sources,
                       with new messages, and merges them into
                       all the language-specific .po files

  make check           Updates everything and then checks everything,
                       printing translation statistics.

In po4a/

  po4a po4a.cfg        Updates all pot and po files

  make preview.LANG    Makes a directory preview.LANG containing
                       translated and compiled manpages which can
                       be previewed with `man -l', and prints a
                       list of appropriate `man -l' commands.
                       (Requires `tcl' to be installed.)


Committing and contributing your translation
--------------------------------------------

When you're done you'll need to commit the changes you have made to
your language's po files.  If you started a new translation, don't
forget to `git add' your new files !

The easiest way to contribute your translation is probably for you to
file a Merge Request on Sala:
  https://salsa.debian.org/dgit-team/dgit

Contributions via the Debian Bug Tracking System are also 
welcome.
