Add TRANSLATE file

Translators may not be familiar with the code base or translation
process. This commit adds a small guide detailing common steps.

1 files changed, 59 insertions, 0 deletions

diff --git a/TRANSLATE b/TRANSLATE
new file mode 100644
index 0000000..1a099d6
--- /dev/null
+++ b/TRANSLATE
@@ -0,0 +1,59 @@
+weltschmerz uses the GNU gettext utilities [1] for translation.
+
+We recommend reading this entire document as well as familiarizing yourself with
+GNU gettext. See [2] for a quick overview.
+
+Note that the commands cited here require having set up a build environment with
+meson. If you have not yet done so, run 'meson build' to create one. The build
+environment now exists in the build/ directory. If you know your way around
+gettext however, you may skip this step and use its tooling instead of the meson
+wrappers discussed below.
+
+INTRO
+
+As a translator, it is your job to create (and maintain) your language's PO file
+for weltschmerz. Initially, that PO file will be created from the "Portable
+Object Template" - a file containing all translatable strings in the program.
+
+This POT file is provided by the author of this software. You can find it (along
+with all other files relevant for translation) in the po/ directory. It is the
+software author's responsibility to keep the POT file up to date so that you as
+a translator do not have to bother updating it. If, however, you happen across a
+string that has not been marked for translation, the author will happily accept
+a patch. Refer to 'UPDATING THE POT FILE' for more information.
+
+ADDING A TRANSLATION
+
+Record the language you intend to add in the LINGUAS file [3] and make sure that
+it is sorted alphabetically. Then, in the build directory, instruct meson to
+generate a PO file for your language:
+
+	meson compile weltschmerz-update-po
+
+There should now be a PO file for your language in the po/ directory. You may
+edit this file with whatever tool you are most comfortable with. If you don't
+know what to use, poedit [4] is a reasonable choice. Refer to [5] if you need
+information on how to translate plural forms.
+
+Once the translation is complete, commit your changes to the LINGUAS file as
+well as your language's PO file to git. You may then submit this commit to the
+author via git-format-patch(1) and git-send-email(1). If you don't know how to
+do this, see [6] for a guide. Feel free to find the author on IRC and ask for
+help if you are struggling.
+
+UPDATING THE POT FILE
+
+Even though the POT file should always be up to date, sometimes you may need to
+regenerate it to pick up on changes to the source code that went unnoticed by
+the author. To do this, run the following command in the build directory:
+
+	meson compile weltschmerz-pot
+
+Please commit and submit this change separately from any translation.
+
+[1] https://www.gnu.org/software/gettext
+[2] https://www.gnu.org/software/gettext/manual/gettext.html#Overview
+[3] https://www.gnu.org/software/gettext/manual/gettext.html#po_002fLINGUAS
+[4] https://poedit.net/
+[5] https://www.gnu.org/software/gettext/manual/gettext.html#Translating-plural-forms
+[6] https://git-scm.com/docs/MyFirstContribution#howto-git-send-email