# HG changeset patch
# User Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
# Date 1552422163 -3600
# Node ID 5b841d56bf742c41768c9d52e6dfb33fc8275b73
# Parent  e3748f24f2562985a6baae86023d09c1309edd0b
i18n: how_to: add instructions to regenerate translations

The wrap value of '76' is determined empirically by checking the total
diff after regeneration using wrap values 70 - 90, using 'wc' to find the
smallest delta. It also corresponds with the help text of Weblate that says
that the default is to 'wrap at 77 characters'.

diff -r e3748f24f256 -r 5b841d56bf74 kallithea/i18n/how_to
--- a/kallithea/i18n/how_to	Tue Mar 12 21:08:02 2019 +0100
+++ b/kallithea/i18n/how_to	Tue Mar 12 21:22:43 2019 +0100
@@ -29,8 +29,8 @@
 necessary corrections when they're needed, or override the false positives.
 
 
-Merging translations from Weblate
----------------------------------
+Merging translations from Weblate (admin-only)
+----------------------------------------------
 
 Weblate rebases its changes every time it pulls from our repository. Pulls are triggered
 by a web hook from Our Own Kallithea every time it receives new commits. Usually merging
@@ -45,6 +45,28 @@
 using its administrative interface.
 
 
+Regenerating translatations after source code changes (admin-only)
+------------------------------------------------------------------
+
+When the Kallithea source code changes, both the location as the content of
+translation strings can change. It is therefore necessary to regularly
+regenerate the `kallithea.pot` file containing these strings, as well as aligning
+the translation files (`*.po`).
+
+First update the translation strings::
+
+    python2 setup.py extract_messages
+
+Then regenerate the translation files. This could either be done with `python2
+setup.py update_catalog` or with `msgmerge` from the `gettext` package. As
+Weblate is also touching these translation files, it is preferred to use the
+same tools (`msgmerge`) and settings as Weblate to minimize the diff::
+
+    find kallithea/i18n -name kallithea.po | xargs -I '{}' \
+        msgmerge --width=76 --backup=none --previous --update '{}' \
+        kallithea/i18n/kallithea.pot
+
+
 Manual creation of a new language translation
 ---------------------------------------------