rewrites and fixes

2 files changed, 42 insertions, 33 deletions

diff --git a/docs/customising/translation.md b/docs/customising/translation.md
index a30782acb..6558be2a0 100644
--- a/docs/customising/translation.md
+++ b/docs/customising/translation.md
@@ -14,18 +14,23 @@ title: Translation
 
 ## Alaveteli's translations
 
-The software translations are implemented using GNU gettext, and the resource
-files are managed in Transifex.
+You don't need to be a programmer to translate Alaveteli -- we use an external
+website called Transifex to help manage translations. This makes it easy for
+translators to get to work, but it does mean you (or your technical team)
+need to do a little extra work to get those translations back into Alaveteli
+when they are ready.
 
 The Transifex project is at
-[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) -- you'll probably want an account there (ask on the mailing
-list). It has a fairly easy-to-use interface for contributing translations.
+[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli)
+-- you'll probably want an account there (ask on the mailing list). It has a
+fairly easy-to-use interface for contributing translations.
 
-There are three roles in the translation process, and each one is described
-below: **translator**, **developer**, and **release manager**. You probably only
-need to know about the one that applies to you.
+Alaveteli implements translations using GNU gettext and `.pot` & `.po` files.
+If you're a developer, you should read
+[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/).
 
-## Translation process: translator's view
+
+## What a translator needs to do
 
 **If you're just working on translating Alaveteli into a language you know, then
 this section is for you.**
@@ -104,14 +109,19 @@ they do not appear on the site anywhere at the moment, and when they do, they
 will only be used in the admin interface. If you do translate them, only
 translate the text that comes *after* the `|`.
 
-## Translation process: developers' view
 
-**If you're writing new code for Alaveteli, then you're a developer, and you
-need to understand how to make any text you add easy for translators to work
-with.**
+## How the translations get into Alaveteli
+
+In order to get the translated strings from Transifex into Alaveteli, follow
+the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes).
+This will be the job of the technical people on your team (or
+even mySociety's release manager) -- if translators aren't technical, they can
+use Transifex without needing to worry about this.
 
-See the page about [internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/).
-You should also read mySociety's [internationalisation
-guide](http://mysociety.github.io/internationalization.html) for our advice on
-using strings that will need translation. This applies across all mySociety
-projects, not just Alaveteli.
+
+## Developers and internationalisation
+
+If you're writing new code for Alaveteli, then you're a developer, and you
+need to understand how to make any text you add easy for translators to work
+with -- see the page about
+[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/).
diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md
index 51d6cada1..521ca5768 100644
--- a/docs/developers/i18n.md
+++ b/docs/developers/i18n.md
@@ -22,17 +22,23 @@ Translations live in the project page at
 [Transifex](https://www.transifex.net/projects/p/alaveteli/) and should
 be submitted there. 
 
-To deploy, say, English and Spanish translations at once:
+For example, to deploy English and Spanish translations at once:
 
  * Ensure their PO files are at ```locale/en/app.po``` and ```locale/es/app.po``` 
    (for example, by downloading them from Transifex)
  * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code>
    to <code>en&nbsp;es</code>
- 
-The ``pot``-file at ``locale/app.pot`` acts as the template for PO files. When
-new translation strings have been added to the source, this ``pot``-file can be
-updated using the script at ``script/generate_pot.sh``. This looks for new
-translatable strings in the source and creates entries in the ``pot``-file.
+
+To update the `.pot` and `.po` files for each language, run:
+
+    bundle exec rake gettext:store_model_attributes
+
+followed by:
+
+    bundle exec rake gettext:find
+
+If `gettext:find` only creates the file `locale/im-config.pot` then you need to
+unset the `TEXTDOMAIN` environment variable and try again.
 
 For more details about the translations, see the page about
 [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/).
@@ -43,7 +49,7 @@ For more details about the translations, see the page about
 ### Getting the current locale
 
 This is complicated by the fact that there are two competing ways to define a
-locale+territory combination. The POSIX (and `gettext` and Transifex) way is
+locale+territory combination. The POSIX (and gettext and Transifex) way is
 like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and
 Transifex for translations, we must deal with both. Wherever you need to know
 the Rails version of the currently selected locale, use `I18n.locale`; wherever
@@ -70,8 +76,7 @@ _('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to ad
    :browse_url => @browse_url, :add_url => @add_url)
 ```
 
-Similar rules can apply to strings in the python source code, as long as you
-import ```_```, ```n_```, etc.
+Similar rules can apply to strings in the Ruby source code.
 
 ## Programmatic access of translated PublicBodies
 
@@ -139,11 +144,5 @@ The release manager will enforce a translation freeze just before a new release
 is cut. During such time, you must not introduce new strings to the code if
 your work is due for inclusion in this release. This is necessary to allow
 translators time to complete and check their translations against all the known
-strings.
-
-## I18n in URLs
+strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/).
 
-We have tried using the [translate_routes plugin](https://github.com/raul/translate_routes)
-to localize URLs. This looks up URL segments as translation strings in a YAML
-file at```config/i18n-routes.yml```. However, we no longer use it because we
-found it was overly complex.