Add translations.bash and translation notes to README.

translations.bash prints some messages from xz, which
hopefully makes it a bit easier to test translations.

1 files changed, 92 insertions, 4 deletions

diff --git a/README b/README
index cbe95578..d6cfda78 100644
--- a/README
+++ b/README
@@ -9,8 +9,9 @@ XZ Utils
        1.3. Documentation for liblzma
     2. Version numbering
     3. Reporting bugs
-    4. Other implementations of the .xz format
-    5. Contact information
+    4. Translating the xz tool
+    5. Other implementations of the .xz format
+    6. Contact information
 
 
 0. Overview
@@ -187,7 +188,94 @@ XZ Utils
     system.
 
 
-4. Other implementations of the .xz format
+4. Translating the xz tool
+--------------------------
+
+    The messages from the xz tool have been translated into a few
+    languages. Before starting to translate into a new language, ask
+    the author that someone else hasn't already started working on it.
+
+    Test your translation. Testing includes comparing the translated
+    output to the original English version by running the same commands
+    in both your target locale and with LC_ALL=C. Ask someone to
+    proof-read and test the translation.
+
+    Testing can be done e.g. by installing xz into a temporary directory:
+
+        ./configure --disable-shared --prefix=/tmp/xz-test
+        # <Edit the .po file in the po directory.>
+        make -C po update-po
+        make install
+        bash debug/translations.bash | less
+        bash debug/translations.bash | less -S  # For --list outputs
+
+    Repeat the above as needed (no need to re-run configure though).
+
+    Note especially the following:
+
+      - The output of --help and --long-help must look nice on
+        a 80-column terminal. It's OK to add extra lines if needed.
+
+      - In contrast, don't add extra lines to error messages and such.
+        They are often preceded with e.g. a filename on the same line,
+        so you have no way to predict where to put a \n. Let the terminal
+        do the wrapping even if it looks ugly. Adding new lines will be
+        even uglier in the generic case even if it looks nice in a few
+        limited examples.
+
+      - Be careful with column alignment in tables and table-like output
+        (--list, --list --verbose --verbose, --info-memory, --help, and
+        --long-help):
+
+          * All descriptions of options in --help should start in the
+            same column (but it doesn't need to be the same column as
+            in the English messages; just be consistent if you change it).
+            Check that both --help and --long-help look OK, since they
+            share several strings.
+
+          * --list --verbose and --info-memory print lines that have
+            the format "Description:   %s". If you need a longer
+            description, you can put extra space between the colon
+            and %s. Then you may need to add extra space to other
+            strings too so that the result as a whole looks good (all
+            values start at the same column).
+
+          * The columns of the actual tables in --list --verbose --verbose
+            should be aligned properly. Abbreviate if necessary. It might
+            be good to keep at least 2 or 3 spaces between column headings
+            and avoid spaces in the headings so that the columns stand out
+            better, but this is a matter of opinion. Do what you think
+            looks best.
+
+      - Be careful to put a period at the end of a sentence when the
+        original version has it, and don't put it when the original
+        doesn't have it. Similarly, be careful with \n characters
+        at the beginning and end of the strings.
+
+      - Read the TRANSLATORS comments that have been extracted from the
+        source code and included in xz.pot. If they suggest testing the
+        translation with some type of command, do it. If testing needs
+        input files, use e.g. tests/files/good-*.xz.
+
+      - When updating the translation, read the fuzzy (modified) strings
+        carefully, and don't mark them as updated before you actually
+        have updated them. Reading through the unchanged messages can be
+        good too; sometimes you may find a better wording for them.
+
+      - If you find language problems in the original English strings,
+        feel free to suggest improvements. Ask if something is unclear.
+
+      - The translated messages should be understandable (sometimes this
+        may be a problem with the original English messages too). Don't
+        make a direct word-by-word translation from English especially if
+        the result doesn't sound good in your language.
+
+    In short, take your time and pay attention to the details. Making
+    a good translation is not a quick and trivial thing to do. The
+    translated xz should look as polished as the English version.
+
+
+5. Other implementations of the .xz format
 ------------------------------------------
 
     7-Zip and the p7zip port of 7-Zip support the .xz format starting
@@ -202,7 +290,7 @@ XZ Utils
         http://tukaani.org/xz/embedded.html
 
 
-5. Contact information
+6. Contact information
 ----------------------
 
     If you have questions, bug reports, patches etc. related to XZ Utils,