This file gives instructions to get you started translating monotone's
diagnostic messages into a new language.  The individual README.<lang>
files in this directory contain copyright information and translation
guidelines for the specific translation.


Help resources
--------------

We have a separate (low-volume) mailing list set up for translation 
issues, where we announce important information and where the translators
can discuss issues on their own.  Please consider subscribing to it:

   <http://lists.nongnu.org/mailman/listinfo/monotone-i18n>


Online translation
------------------

monotone has a Transifex project registered, which you can use to translate
your strings online:

   <http://www.transifex.net/projects/p/monotone/>

Your changes there might not be noticed immediately, so please drop us
a note either by private mail or on the above mentioned mailing list,
so we can pull your translation updates from there.


Traditional translation
-----------------------

You can - of course - also just start with a new translation by checking
out the latest source and work on the command line.  Be aware though that
we do not use the usual (gettext-provided) Makefile logic for .po files,
so some of the commands below may be different from what you are used to.
Note especially that all "make" commands are done from the top level of
the tree, *not* from the po subdirectory.  Also, the .pot file and the
.merged.po and .gmo files created during a build appear in the po
subdirectory.

Before you begin:

a) You should be comfortable with shell commands.
b) You need a text editor with UTF-8 support, and maybe one of the
   specialized PO-file editors mentioned below.
c) You need a working "mtn" executable and the command line tools from
   the "gettext" package (xgettext, msgfmt, msgmerge).

Now the step-by-step HOWTO:

0) Pull a local copy of monotone's version control database from
   monotone.ca (you only need the main branch, net.venge.monotone)
   and check out the main branch.  If you're reading this, you have
   probably done this already :-)

1) Add an line for your language to the file po/LINGUAS.  This file
   simply lists the ISO 639-1 codes for supported translations, one
   per line (e.g. "en" for English, "de" for German, etc.)  If your
   language differs by region, you can append an underscore and an

   ISO 3166-1 country code to the language code for each regional
   variant you wish to support.  For instance, monotone currently has
   a translation file for Brazilian Portuguese (pt_BR) but not
   Portugal Portuguese (pt_PT).  (Note: the pt_BR translation has not
   been updated for some time, so it is not included in po/LINGUAS.)

2) Create a template file:
  
   $ cd <your source directory>
   $ autoreconf --install
   $ ./configure
   $ make po/monotone.pot

   This will create the file po/monotone.pot, which lists every message
   that you need to translate.  Copy this file to po/CODE.po (again,
   replace CODE with the code you added to po/LINGUAS).
   
3) Fill out the header of your new .po file.  This mailing list post
   gives excellent advice on how to do so:

     <http://mail.gnome.org/archives/gnome-i18n/2004-July/msg00073.html>

   and you may also wish to consult the relevant section of the
   gettext manual:

     <http://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html>

   ATTENTION: Do not change the generic comment as hinted in the above
              resources, but rather create a separate README.CODE which
              contains your copyright and any additional information you want
              to give possible contributors.  This is needed because the
              online translation system Transifex removes / replaces these
              comments with generic information, and these unwanted changes
              might get back into our tree by accident.

   Two of the fields in the remaining header also deserve special attention:

   a) The encoding of the file (Content-Type: ...)  Set this to the
      encoding you'll use in your text editor to translate the
      file. We strongly recommend the use of UTF-8.

   b) The pluralization rules (Plural-Forms: ...)  In English, nouns
      have different endings when there is only one object mentioned
      ("1 frog") than when there are more than one ("10 frogs").  All
      the messages that need to vary like this should be listed in the
      template with both a "msgid" and a "msgid_plural", and you can
      provide as many variations on the translation as you need for
      proper grammar.  The Plural-Forms: header tells the library
      which variation to use when.  For instruction in writing this
      header, please see the gettext manual:

        <http://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html>

      (By the way, if you find a message that should vary this way but
      doesn't list a plural form in the template file, please tell us
      about it on monotone-dev.)

4) Start translating the entries.  When finished, commit the new .po
   file and push your changes to monotone.ca.  Don't forget to commit
   po/LINGUAS and po/README.CODE as well.

   If you're looking for a nice GUI to edit language files, we
   recommend KBabel, which comes with the kdesdk module of KDE, or
   poedit.  See these websites:

     <http://kbabel.kde.org>
     <http://www.poedit.net>

5) To update your template when the sources change, you can use this
   command:

   $ make po/CODE.po-update

   This will update monotone.pot from the sources and then use the
   "msgmerge" utility to update your translation.  It updates
   po/CODE.po in place.  If you prefer for this not to happen, you can
   instead do

   $ make po/CODE.merged.po

   which will drop the new .po file, with a ".merged.po" extension, in
   the directory where you ran "make".  You can then edit that file
   and copy it to po/CODE.po when you like.

   To check if new or fuzzy strings have arrived, use msgfmt:

   $ msgfmt -cv po/CODE.po  # or po/CODE.merged.po

