Update translation documentation to reflect proposed new workflow

2 files changed, 73 insertions, 30 deletions

diff --git a/doc/TRANSLATE.md b/doc/TRANSLATE.md
index 0fe85504b..19d038472 100644
--- a/doc/TRANSLATE.md
+++ b/doc/TRANSLATE.md
@@ -3,41 +3,70 @@ resource files are managed in Transifex.
 
 The Transifex project is at
 https://www.transifex.net/projects/p/alaveteli/; you'll probably want
-an account there (ask on the mailing list).
+an account there (ask on the mailing list).  It has a fairly easy to
+use interface for contributing translations.
 
-# Summary
+# Translation process: translator's view
 
-1. Make some changes to the software with `_('translatable strings')`
-2. Temporarily move any theme containing translations out of the way (there's a bug in gettext_i18n_rails that can't cope with translation chains)
-3. Run `./script/generate_pot.sh`
-4. This should just cause the file at `locale/app.pot` to change.  Commit and push
-5. Move your theme back in place
-6. Send a message to the alaveteli-dev mailing list warning them that you're going to upload this file to transifex
-7. Wait a day or so to make sure they've uploaded any of their outstanding translations and have a copy of any old ones
-8. Update the `app.pot` resource in Transifex
-9. When new translations are available, run `tx pull -a` and commit the results to the repository
+When a developer adds a new feature to the user interface in
+Alaveteli, they use some code to mark sentences or words ("strings")
+that they think will need to be translated.
 
-# Detail
+When the Alaveteli release manager is planning a release, they upload
+a template containing all the strings to be translated (called a POT)
+to Transifex.  This causes your own translations in Transifex to be
+updated with the latest strings.
 
-## Finding new translatable strings
+When you visit Transifex, it will prompt you to fill out values for
+all new strings, and all strings that have been modified.  In the case
+where a string has only been slightly modified, such as with
+punctuation ("Hello" has become "Hello!"), Transifex will suggest a
+suitable translation for you (look for the "suggestions" tab under the
+source string).
 
-To update the POT file with strings from the software source, run
-`rake gettext:find` from the Alaveteli software.  The script at
-`./script/generate_pot.sh` does this for you.
+In order for this feature to work properly, the release manager has to
+download your translations, run a program that inserts the
+suggestions, and then upload them again.  Therefore, when a release
+candidate is announced, make sure you have uploaded any outstanding
+translations, or you will lose them.
 
-When you've changed the POT file, and committed it, you should warn
-people on the mailing list before logging into Transifex and pressing
-the button to import it into that system.  Otherwise, translators
-might lose some of their old but useful translations.
+When a release candidate has been annouced, there is a **translation
+freeze**: during this period, developers must not add any new strings
+to the software, so you can be confident that you're translating
+everything that will be in the final release.
 
-## Pulling translations from Transifex
-  
-To update the local translation files using the Transifex command-line client, first install it:
+The release manager will also give you a **translation deadline**.  After
+this date, you can continue to contribute new translations, but they
+won't make it into the release.
 
-    # easy_install transifex-client
-  
-Then you can run the following from the root of your Alaveteli install:
+# Translation process: release manager's view
 
-    tx pull -a
-    
-Finally, commit these translations to github as usual.
+Before the Alaveteli release manager cuts a new release branch, they
+must:
+
+* pick a date for the release branch to be cut ("release candidate date")
+* make an announcement to the translators (using the "announcements"
+  feature in Transifex) that they should ensure they have any pending
+  translations saved in Transifex before the release candidate date
+* make an announcement to the developers that all new strings should
+  be committed before the release candidate date
+* on the release candidate date:
+    * download (`tx pull -a -f`) and commit all the current translations (important:
+      there's no revision history in Transifex!)
+    * regenerate the POT file and individual PO files for each language,
+      using `./script/generate_pot.sh` (which calls `rake gettext:find`, etc)
+        * this updates the PO template, but also merges it with the
+          individual PO files, marking strings that have only changed
+          slightly as "fuzzy"
+	* you must emporarily move any theme containing translations out of the way (there's a bug in gettext_i18n_rails that can't cope with translation chains)
+    * reupload (`tx push -t`) the POT and PO files to Transifex
+        * The point of uploading the PO files is that Transifex converts the "fuzzy" suggestions from Transifex into "suggestions" under each source string
+        * Note that Transifex *does not* preserve fuzzy strings in the PO files it makes available for download, on the grounds that Transifex supports multiple suggestions, whereas gettext only allows one fuzzy suggestion per msgid.
+    * remove the fuzzy strings from the local PO files (because they make
+      Rails very noisy), and then commit the result. You can do this by re-pulling from Transifex.
+* on the release date:
+    * download and commit all the current translations
+
+# Translations: developers' view
+
+See the [I18n guide](https://github.com/sebbacon/alaveteli/wiki/I18n-guide) on the wiki.
diff --git a/script/generate_pot.sh b/script/generate_pot.sh
index 0c5dfda36..f6c82dda7 100755
--- a/script/generate_pot.sh
+++ b/script/generate_pot.sh
@@ -1,8 +1,22 @@
 #!/bin/bash
 
+echo "This is NOT a completed script! Just use it as reference for what to do from the command line, or fix it until it works!"
+exit 1
+
 cd `dirname $0`
+# grab latest po files from Transifex
+tx pull -a -f
+git status | grep app.po | awk '{print $3}' | xargs git add
+git commit -m "Backup latest po files from Transifex"
 
+# now regenerate POT and PO files from Alaveteli source
 rake gettext:store_model_attributes
 rake gettext:findpot
 
-echo "Now commit the new app.pot and push.  See TRANSLATE.md for next steps"
\ No newline at end of file
+# upload the result to Transifex
+tx push -t 
+
+# re-download (it removes the fuzzy strings and normalises it to the format last committed)
+tx pull -a -f
+git status | grep app.po | awk '{print $3}' | xargs git add
+git commit -m "Updated POT"