update docs

2 files changed, 100 insertions, 5 deletions

diff --git a/HACKING/licensing.md b/HACKING/licensing.md
index 6d17e31..ec83689 100644
--- a/HACKING/licensing.md
+++ b/HACKING/licensing.md
@@ -6,14 +6,12 @@ New code should (please) be licensed GPLv2+.  I say v2 instead of v3
 because some code from Arch is GPLv2 (no "or any later version"), and
 having to worry about which programs can be combined is a huge pain.
 
-Copyright statements should look like
+Copyright statements for most code, should be of the form:
 
 	# Copyright (C) YEARS NAME <EMAIL>
 
-for most code, for 3rd-party code that has been imported, indent it a
-bit:
+For 3rd-party code, which has been imported, indent it a bit:
 
 	#   Copyright (C) YEARS NAME <EMAIL>
 
-Always put a line with `# License:` specifying the license of that
-file.
+Always put a `# License:` line specifying the license of that file.
diff --git a/HACKING/translations.md b/HACKING/translations.md
new file mode 100644
index 0000000..09de59b
--- /dev/null
+++ b/HACKING/translations.md
@@ -0,0 +1,97 @@
+Translations for programs are provided in files with the `.po` suffix. These are
+created by copying PO-template (`.pot`) files, and filling in the missing
+"msgstr" values.
+
+To add a translation, you'll first (1) need to create the `.pot` files if you
+don't already have them, and then (2) copy them and (3) fill them in.
+
+## 1. Create the `.pot` files
+
+If you are working from a release source tarball, you can skip this step (the
+`.pot` files are included in the tarball); if you are working from git, read on.
+
+libretools' .pot files are not tracked in git; they are created by running
+`make`.  You'll need a checkout of both 'devtools-par' and 'libretools' to run
+`make` if building from git. The 'devtools-par' and 'libretools' source root
+directories should have the same parent directory.
+
+    $ git clone https://git.parabola.nu/packages/libretools.git/
+    $ git clone https://git.parabola.nu/packages/devtools-par.git/
+    $ cd libretools
+    $ make po/files.generate
+    $ cd po/
+    $ ls
+    gitget.pot
+    librelib.pot
+    libretools.pot
+
+NOTE: If you have modified the libretools source code, that may cause errors
+during translation; especially if you have modified any of the translatable
+strings. The failure will be evident by the error message:
+
+    msgcmp: found N fatal errors
+
+If you see this error, refer to the "Updating translations" section below.
+
+## 2. Create the `.po` Files
+
+Create a folder under `po/` with the two-letter language code[^1] you want to
+add.  Then, copy the `.pot` files to that folder, changing the file extension to
+`.po`.  Finally, link the `subdir.mk` file as the Makefile for that directory.
+For example:
+
+    $ mkdir es
+    $ for file in *.pot; do cp $file es/${file%t}; done
+    $ ln -s ../subdir.mk es/Makefile
+
+[^1]: See the langauge code table: <http://www.lingoes.net/en/translator/langcode.htm>
+
+## 3. Fill the `.po` Files
+
+From there you can open each .po file in your favorite text editor, and fill in
+the `msgstr` values with translations of the associated `msgid` keys.
+
+## 4. Synchronizing/Updating Translations
+
+If you have modified the libretools source code, it is likely that the program
+will fail to compile, due to the translation files being mis-aligned with the
+latest changes. You will need to run `msgmerge` to merge the newly generated
+.pot templates into the existing .po files, as indicated by the `msgcmp` command
+trace in the build log.
+
+e.g. if the following error message appeers after this log trace:
+
+    msgcmp --use-untranslated --use-fuzzy po/es/libretools.po po/libretools.pot
+    ....
+    msgcmp: found 42 fatal errors
+
+then run:
+
+    $ msgmerge po/es/libretools.po po/libretools.pot
+
+Notice any red (fuzzy) lines. Those are relatively minor mis-matches, which the
+tool was able to reconcile, but may need correction. Also notice any green,
+commented-out, 'msgid'/'msgstr' line pairs. Those are unresolved mis-matches,
+which definitely need correction. They may correspond to a new 'msgid'/'msgstr'
+line pair in the `msgmerge` output, with the new text as 'msgid', and an empty
+'msgstr'; but the changes were too significant for the tool to determine the
+correlation. The standard output of `msgmerge` is the raw text for a new
+replacemnt .po file. Next, direct the output to a file, make the corrections
+to the replacemnt .po file, using the `msgmerge` output as a guide. A merge tool
+such as `meld`, is especially helpful for this task. A merge tool should
+highlight the same merge conflicts, shown in the the `msgmerge` output, as a
+side-by-side comparison. You want to merge all of the changes, including line
+numbers (eg: # src/chroot-tools/libremakepkg:42)
+
+    $ msgmerge po/es/libretools.po po/libretools.pot > po/es/libretools.po-merged
+    $ meld po/es/libretools.po{-merged,}
+
+Then delete the failed .po file, which is under sorce control, replace it with
+the new corrected file.
+
+    $ mv po/es/libretools.po{-merged,}
+
+Once `make clean && make` is able to complete successfully, commit the new .po
+file to the VCS.
+
+    $ git commit -m 'sync translations' po/es/libretools.po