[Zope3-checkins] SVN: Zope3/branches/Zope-3.1/src/zope/app/locales/TRANSLATE.txt give the document a major work over

[Philipp von Weitershausen]

Log message for revision 37740:
  give the document a major work over
  

Changed:
  U   Zope3/branches/Zope-3.1/src/zope/app/locales/TRANSLATE.txt

-=-
Modified: Zope3/branches/Zope-3.1/src/zope/app/locales/TRANSLATE.txt
===================================================================
--- Zope3/branches/Zope-3.1/src/zope/app/locales/TRANSLATE.txt	2005-08-05 18:56:59 UTC (rev 37739)
+++ Zope3/branches/Zope-3.1/src/zope/app/locales/TRANSLATE.txt	2005-08-05 18:57:56 UTC (rev 37740)
@@ -2,32 +2,57 @@
 Internationalization (I18n) and Localization (L10n)
 ===================================================
 
+This document assumes that you have a Zope 3 checkout and the gettext
+utilities installed.
 
+
 Creating/Updating Message Catalog Template (POT) Files
 ------------------------------------------------------
 
-1. Execute i18nextract.py from Zope's utilities/ directory::
+Whenever you've made a change to Zope that affects the i18n messages,
+you need to re-extract i18n messages from the code.  To do that,
+execute ``i18nextract.py`` from the ``utilities`` directory of your
+Zope 3 checkout:
 
-     python2.3 i18nextract.py
+  $ python utilities/i18nextract.py -p src/zope/app -o locales
 
+This will update the ``zope.pot`` file.  After that, you need to merge
+those changes to all existing translations.  You can do that by
+executing the ``i18nmergeall.py`` script from the ``utilities``
+directory of your Zope 3 checkout:
 
-Updating Message Catalog (PO) Files
-------------------------------------
+  $ python utilities/i18nmergeall.py -l src/zope/app/locales
 
-1. For each language do simply::
 
-     msgmerge -U de/LC_MESSAGES/zope.po zope.pot
+Translating
+-----------
 
-2. Translate the updated PO file. 
-   Note: KBabel is a great tool for this task!
+To translate messages you need to do the following steps:
 
+1. If a translation for your language is already present and you just
+   want to update, skip ahead to step 2.  If you want to start
+   translation on a new language, you need to
 
-Compiling Message Catalogs (PO) to binary (MO) Files
-----------------------------------------------------
+   a) create a directory
 
-1. Go to the right directory, such as
-   zope/app/locales/de/LC_MESSAGES.
+        src/zope/app/locales/<lang_code>/LC_MESSAGES
 
-2. Run the following command::
+      with the appropriate code for your language as <lang_code>.
+      Note that the two letters specifying the language should always
+      be lower case (e.g. 'pt'); if you additionally specify a region,
+      those letters should be upper case (e.g. 'pt_BR').
 
-     msgfmt -o zope.mo zope.po
+   b) copy the ``zope.pot`` template file to
+      ``<lang_code>/LC_MESSAGES/zope.po``.
+
+   c) edit the PO header of the newly created ``zope.po`` file and
+      fill in all the necessary information.
+
+2. Translate messages within the PO file.  Make sure the gettext
+   syntax stays intact.  Tools like poEdit and KBabel can help you.
+
+3. Finally, when you're done translating, compile the PO file to its
+   binary equivalent using the ``msgfmt`` tool:
+
+   $ cd <lang_code>/LC_MESSAGES
+   $ msgfmt -o zope.mo zope.po