i18n: Update po/README to discuss document translation

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 77 insertions, 22 deletions

diff --git a/po/README b/po/README
index 5541daa..7aadce0 100644
--- a/po/README
+++ b/po/README
@@ -8,17 +8,19 @@ The dgit source package contains dgit and git-debrebase.
 These are useful for a variety of different users and in different
 situations.  So there are various documents aimed at various users.
 
-* dgit supports message translation.
+* dgit and git-debrebase both support message translation.
 
-* Documentation translation is TBD.
+* 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,
-  but this will change and its translation will then be more
-  important.  Message translation is mostly not supported right now.
+  but this will change and its document translations will then be more
+  important.
 
-The en_US 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 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.
 
 
 Translatation priorities
@@ -26,23 +28,23 @@ Translatation priorities
 
   HIGH
 
-    dgit-user(1)       How to use dgit to as a downstream or user
-  *** NB that documentation translation is TBD so you cannot do this yet ***
+    po4a/dgit-user_1.pot    How to use dgit to as a downstream or user
 
   MEDIUM
 
-    messages.pot
-    dgit.1
-    dgit-downstream-dsc.7
-    dgit-sponshorship.7
-    dgit.7
+    po/messages.pot         All the messages for both programs
+
+    po4a/dgit_1
+    po4a/dgit-downstream-dsc_7
+    po4a/dgit-sponshorship_7
+    po4a/dgit_7
 
   LOW
 
-    dgit-maint-*       } For work within the Debian project
-    dgit-nmu-simple.7  }  (where one needs good English anyway)
+    po4a/dgit-maint-*       } For work within the Debian project
+    po4a/dgit-nmu-simple_7  }  (where one needs good English anyway)
 
-    git-debrebase.*    Currently low priority but this will change
+    po4a/git-debrebase_*    Currently low priority but this will change
 
 
 Translation organisation
@@ -52,13 +54,57 @@ Translation organisation
   po/LANG.po           translations of those
   po/mo                output directory, do not look here
 
-  po4a/                documentation (TBD)
+  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 definining 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
+--------------------
 
-Important make targets for translators.
-NB all of these are after "cd po/".
+In po/
 
-  make <LANGUAGE>.po   Creates <LANGUAGE>.po so you can start translating,
-                       or update messages.pot <LANGUAGE>.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 all-po          Updates messages.pot from all the sources,
                        with new messages, and merges them into
@@ -66,3 +112,12 @@ NB all of these are after "cd po/".
 
   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.