rewritten i18n/translation pages with @crowbot's comments in mind

1 files changed, 21 insertions, 8 deletions

diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md
index 521ca5768..deabc99a1 100644
--- a/docs/developers/i18n.md
+++ b/docs/developers/i18n.md
@@ -18,18 +18,30 @@ title: Internationalisation (for devs)
 
 Deployed translations for the project live in ``locale/``.
 
-Translations live in the project page at
-[Transifex](https://www.transifex.net/projects/p/alaveteli/) and should
-be submitted there. 
+We encourage translations to be done on
+[Transifex](https://www.transifex.net/projects/p/alaveteli/)
+because translators can work through its web interface rather than needing to edit the
+<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a>
+directly. Ultimately, Transifex just captures translators'
+work and turns it into the files that Alaveteli needs (using gettext).
+
+### How to get the latest translations onto your site
 
 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``` 
+ * 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>
 
-To update the `.pot` and `.po` files for each language, run:
+### How to add new strings to the translations
+
+You need to do this if you've added any new strings to the code that need
+translations (or if you change an existing one).
+
+To update the
+<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a>
+for each language, run:
 
     bundle exec rake gettext:store_model_attributes
 
@@ -51,9 +63,10 @@ For more details about the translations, see the page about
 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
 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
-you want to know the POSIX version of the locale, use `FastGettext.locale`.
+Transifex for translations, we must deal with both. 
+
+   * for the Rails version of the currently selected locale, use `I18n.locale`
+   * for the POSIX version of the locale, use `FastGettext.locale`
 
 ## I18n in templates