[kupfer: 7/11] Manual.rst: Heroic rewrite of localization part

[Ulrik Sverdrup <usverdrup src gnome org>]

commit 06aeb13893edfbae670f2f4fb28001ae5abf8c05
Author: Ulrik Sverdrup <ulrik sverdrup gmail com>
Date:   Sun Nov 1 18:41:28 2009 +0100

    Manual.rst: Heroic rewrite of localization part

 Documentation/Manual.rst |   83 +++++++++++++++++++++++++++++++--------------
 1 files changed, 57 insertions(+), 26 deletions(-)
---
diff --git a/Documentation/Manual.rst b/Documentation/Manual.rst
index ad99137..04af786 100644
--- a/Documentation/Manual.rst
+++ b/Documentation/Manual.rst
@@ -3,7 +3,7 @@ kupfer
 ======
 
 :Author: Ulrik Sverdrup
-:Date: Wednesday, 23 September 2009
+:Date: Sunday,  1 November 2009
 :Revision: $Id$
 :Homepage: http://kaizer.se/wiki/kupfer
 
@@ -276,57 +276,88 @@ Localization
 ============
 
 kupfer is translated using gettext and it is managed in the build system
-using intltool. Translation messages are located in the po/ directory.
+using ``intltool``. Translation messages are located in the ``po/``
+directory.
+
+Kupfer's localizations are listed among Gnome's modules. Its homepage
+is:
+
+    http://l10n.gnome.org/module/kupfer/
+
+You can download the latest version of your language's translation file
+there, if Kupfer is already translated to your language.
 
 To update or check an existing translation
 ------------------------------------------
 
-To update with new strings, run::
+Go to your Kupfer source directory.
+
+Here we will call your language ``$LANG``. You should use a two or
+four-letter code for your language instead of ``$LANG``, for example
+"de" for German or "pt_BR" for Brazilian Portuguese.
+
+Go to the translation directory ``po``::
+
+    cd po/
+
+To update and check the translation file, run::
 
-    ./waf intlupdate
+    intltool-update $LANG
 
-Then check all fuzzy messages, translate all untranslated messages.
-Continue running ``./waf intlupdate`` to check that you have 0 fuzzy and
-0 untranslated, then you're finished. ``./waf intlupdate`` will also run
-a check of the consistency of the file, so that you know that all syntax
-is correct.
+Now check and edit ``$LANG.po``. Search for all messages marked "fuzzy",
+and remove the word "fuzzy" from them when they are done.
+
+Continue running ``intltool-update $LANG`` and check that you have 0
+fuzzy and 0 untranslated, then you're finished.
+
+This will also check consistency of the file, so that you know that all
+your syntax is correct.
 
 If you want to send in the translation to a repository, or as a patch,
 you can use git if you have a checked-out copy of kupfer::
 
-    git add po/lang.po
-    git commit -m "lang: Updated translation"
+    git add po/$LANG.po
+    git commit -m "$LANG: Updated translation"
 
     # now we create a patch out of the latest change
     git format-patch HEAD^
 
-where ``lang`` is the two-letter abbreviation. You can send the patch to
-the mailing list kupfer-list gnome org 
-
+You can send the patch, or the whole file, to the mailing list
+kupfer-list gnome org 
 
 To create a new translation
 ---------------------------
 
-Add the language to ``po/LINGUAS`` with its (commonly) two-letter code.
-Run ``./waf intlupdate`` and then edit the header in the ``po/lang.po``
-file, filling in your name and other slots, and importantly the CHARSET.
-Kupfer translations *must* use the UTF-8 encoding.
+Go into the directory ``po``
+
+1. Add the language code ``$LANG`` to the file ``LINGUAS``
+2. Run ``intltool-update --pot``, and copy ``untitled.pot`` to ``$LANG.po``
+3. Edit and check the whole file header: 
 
-When the header is filled-in, run ``./waf intlupdate`` to see that it
-runs without errors, and you should have a ``po/lang.po`` file ready for
-translating.
+   + Write in yourself as author
+   + Check ``plurals`` (copy from a language that you know uses the same
+     number of plural forms, or look up in Gnome's translation pages.)
+   + Replace everything written in CAPS
+
+Fill in the charset used; Kupfer translations *must* use the UTF-8 encoding.
+
+When the header is filled-in, go to `To update or check an existing
+translation`_
 
 To try the new translation
 --------------------------
 
 Make sure the translation is listed in ``po/LINGUAS``.
 
-To try it, you have to install kupfer with ``./waf install``
+To try it, you have to install kupfer with ``./waf install``, then you
+can run kupfer as normal.
+
+.. note::
 
-If you run ``./kupfer-activate.sh`` from the working directory it won't
-find the installed translations unless you make a symlink called
-``locale`` to the installed location (for example
-``~/.local/share/locale`` if install prefix was ``~/.local``).
+    If you run ``./kupfer-activate.sh`` from the source directory it won't
+    find the installed translations unless you make a symlink called
+    ``locale`` to the installed location (for example
+    ``~/.local/share/locale`` if install prefix was ``~/.local``).
 
 
 Copyright