Build: move translations from install/po/ to top-level po/

Translations are need for client as well. This move is done to remove
dependency between client and install subdirectories.

https://fedorahosted.org/freeipa/ticket/6418

Reviewed-By: Lukas Slebodnik <lslebodn@redhat.com>
Reviewed-By: Stanislav Laznicka <slaznick@redhat.com>
Reviewed-By: Christian Heimes <cheimes@redhat.com>

1 files changed, 143 insertions, 0 deletions

diff --git a/po/README b/po/README
new file mode 100644
index 000000000..6894a0633
--- /dev/null
+++ b/po/README
@@ -0,0 +1,143 @@
+Q: I've added a new source file, how do I make sure it's strings get translated?
+
+A: Edit Makefile.in and add the source file to the appropriate *_POTFILES list.
+   Then run "make update-po".
+
+   NOTE: Now this i only necessary for python files that lack the .py
+         extension. All .py, .c and .h files are automatically sourced.
+
+Q: Untranslated strings and file locations are missing from my .po file.
+   How do I add them?
+
+A: make merge-po
+   Untranslated strings are left out of the files in SCM. The merge-po command
+   runs msgmerge to add them again.
+
+Q: How do I pick up new strings to translate from the source files after the
+   source have been modified?
+
+A: make merge-po
+   This regenerates the pot template file by scanning all the source files.
+   Then the new strings are merged into each .po file from the new pot file.
+
+Q: How do I just regenerate the pot template file without regenerating all the
+   .po files?
+
+A: make update-pot
+
+Q: I am done translating. How do I commit my changes?
+
+A: Run `make strip-po` to remove unneeded information from the po files, then
+   add your changes to SCM.
+
+Q: How do I add a new language for translation?
+
+A: Edit the LINGUAS file and add the new language. Then run "make create-po".
+   This will generate a new .po file for each language which doesn't have one
+   yet. Be sure to add the new .po file(s) to the source code repository.  For
+   certain languages, you may have to edit the Plurals line.  See:
+   http://www.gnu.org/software/hello/manual/gettext/Plural-forms.html
+   However, if this line is wrong, it is often an indicator that the locale
+   value is incorrect.  For example, using 'jp' for Japanese in stead of 'ja'
+   will result in an invalid Plurals line.
+
+Q: What files must be under source code control?
+
+A: The files Makefile.in, LINGUAS control the build, they must be in the SCM.
+   The *.pot and *.po files are used by translators, they must be in SCM so the
+   translator can checkout out a .po files, add the translations, and then check
+   the .po file back in.
+
+   Be careful, .po files may be automatically updated when the source files
+   change (or the .pot changes, usually the .pot file changes only as a result
+   of rescanning the source files). This mean a .po file might be automatically
+   updated while a translator has the file out for editing, all the caveats
+   about SCM merging apply.
+
+Q: Which are automatically generated and thus do not need to be in SCM?
+
+A: The *.mo files are automatically generated on demand from their corresponding
+   .po file. 
+
+Q: What role does the .pot file play?
+
+A: The .pot file is called a template file. It is generated by scanning all the
+   source files (e.g. *.py *.c *.h) in the project using xgettext. xgettext
+   locates every translatable string (e.g. strings marked with _()) and adds
+   that string along with metadata about it's location to the .pot file. Thus
+   the .pot file is a collection of every translatable string in the project. If
+   you edit a source file and add a translatable string you will have to
+   regenerate the .pot file in order to pick up the new string.
+
+Q: What is the relationship between a .po file and the .pot file?
+
+A: A .po file contains the translations for particular language. It derives from
+   the .pot file. When the .pot file is updated with new strings to translate
+   each .po will merge the new strings in. The .po file is where translators
+   work providing translations for their language. Thus it's important the .po
+   not be recreated from scratch and is kept in SCM, otherwise the translators
+   work will be lost.
+
+   Let's use an example for French, it's .po file will be fr.po.
+
+   1)  Developer creates main.c with one translatable sting _("Begin").
+
+   2)  Produce the .pot file by running xgettext on main.c
+
+   3)  .pot file contains one msgid, "Begin" 
+
+   4)  fr.po is created from the .pot file, it also contains one msgid, "Begin"
+
+   5)  Translator edits fr.po and provide the French translation of "Begin".
+
+   6)  Developer adds new translatable sting _("End") to main.c
+
+   7)  Generate a new .pot file by running xgettext on main.c
+
+   8)  .pot file contains two msgid's, "Begin", and "End"
+
+   9)  fr.po is missing the new msgid in the .pot file, so the .pot is merged
+       into fr.po by running msgmerge. This copies into fr.po the new "End" msgid
+       but preserves the existing translations in fr.po (e.g. "Begin"). The fr.po
+       will now have 2 msgid's one which is translated already (e.g. "Begin") and
+       one that untranslated (e.g. "End").
+
+   10) Sometime later the French translator comes back to see if he/she needs to
+       add more translations to fr.po. They see there is a missing translation,
+       they check fr.po out from SCM, add the missing translation, and then
+       check fr.po back into SCM.
+
+   This means at any given moment the set of .po files will have varying degrees
+   of translation completeness. Because the .po files are merged when the source
+   code files are updated existing translations are not lost. It also means a
+   .po file which was fully translated may need new translations after a .pot
+   update. It is permissible to have incomplete translations in a message
+   catalog, at run time if a translation for a particular string is available in
+   the message catalog the user will be presented with the string in their
+   language. However if the string is not yet translated in the .po file then
+   they just get the original string (typically in English).
+
+Q: What are .mo files?
+
+A: .mo files are the content of a .po file but in "machine" format for fast
+   run time access (mo = Machine Object, po = Portable Object). .mo files are
+   what gets installed along with the package. Think of a .po as a source file
+   which is compiled into a object file for run time use.
+
+Q: Why don't we use gettexize and autopoint?
+
+A: Because the framework they produce is too limited. Specifically there is no
+   way to pass the source language to xgettext when it scans a file. xgettext
+   only knows how to automatically determine the language from the source files
+   extension. However we have many files without extensions, thus we have to
+   group all Python (et. al.) files together and run xgettext on every file *we*
+   know to Python (because xgettext can't figure this out itself if there is no
+   file extension). There is another added benefit of avoiding gettextize and
+   autopoint, simplicity. Managing translations is complex and hard enough as it
+   is, gettextize and autopoint adds another whole layer of complexity which
+   just further obscures things.
+
+Q: Who created the awful mess and who do I ask when things don't work as I
+   expect or I have further questions?
+
+A: John Dennis <jdennis@redhat.com>