1 files changed, 123 insertions, 0 deletions
diff --git a/install/po/README b/install/po/README
new file mode 100644
index 000000000..e032e3529
--- /dev/null
+++ b/install/po/README
@@ -0,0 +1,123 @@
+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".
+
+Q: How do I pick up new strings to translate from the source files after the
+   source have been modified?
+
+A: make update-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: 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.
+
+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>