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

2 files changed, 76 insertions, 15 deletions

diff --git a/docs/customising/translation.md b/docs/customising/translation.md
index 6558be2a0..d4ccedfa7 100644
--- a/docs/customising/translation.md
+++ b/docs/customising/translation.md
@@ -12,6 +12,39 @@ title: Translation
 	it. This page explains how.
 </p>
 
+## Alaveteli already contains translations!
+
+Alaveteli ships ready to run in a number of different languages.
+If Alaveteli has already been translated into the language (or languages) you
+need, you just need to configure it -- see
+[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales).
+
+[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale)
+to see what translations are already available. Some are complete
+translations of the site. Others are only partial -- either because the translations
+have not been finished yet, or else because the translators have not updated the
+texts since developers changed or added text on the site.
+
+There are two reasons the translations may need more work before you can use them:
+
+* **the language you want is not one of those we already have** <br> In this
+  case, there will be no entry in ``locale/`` for it, because nobody has yet
+  translated Alaveteli into your language. See the rest of this page to learn
+  how to add a new translation.
+
+* **the translation for your language is incomplete, or lagging behind** <br>
+  This might simply be because it is a work in progress. Furthermore, sometimes
+  an incomplete translation already covers all the areas of the site you need
+  anyway. Of course, you can add to a partial translation, but it's a good idea
+  to check with us first, since we'll probably know who is working on the
+  current translation and what state it's in.
+
+Translators are members of the Alaveteli
+[community]({{site.baseurl}}community/), and often work separately from the
+developers. This means translations can lag a little behind the code. However,
+our release process includes a "translation freeze", which gives the
+translators a chance to catch up -- read the rest of this page for details.
+
 ## Alaveteli's translations
 
 You don't need to be a programmer to translate Alaveteli -- we use an external
@@ -25,7 +58,8 @@ The Transifex project is at
 -- you'll probably want an account there (ask on the mailing list). It has a
 fairly easy-to-use interface for contributing translations.
 
-Alaveteli implements translations using GNU gettext and `.pot` & `.po` files.
+Alaveteli localises strings using GNU gettext and
+<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> &amp; <code>.po</code> files</a>.
 If you're a developer, you should read
 [internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/).
 
@@ -35,20 +69,28 @@ If you're a developer, you should read
 **If you're just working on translating Alaveteli into a language you know, then
 this section is for you.**
 
+> Remember that Alaveteli
+> [already comes with some translations](#alaveteli-already-contains-translations),
+> so check first that you really need to do this. Maybe someone has already
+> translated Alaveteli into the language you need!
+
 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.
 
-When the Alaveteli release manager is planning a release, they will 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
+When the Alaveteli
+<a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release manager</a>
+is planning a release, they will upload a
+template containing all the strings to be translated (called a
+<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>)
+to Transifex. This causes your own translations in Transifex to be updated with
 the latest 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).
+*Suggestions* tab under the source string).
 
 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
@@ -64,11 +106,12 @@ 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.
 
+
 ### General notes on translation in Transifex
 
 Some strings will have comments attached to them from the Alaveteli
 application developers about the context in which the text appears in the
-application — these comments will appear under the 'Details' tab for the text
+application — these comments will appear under the *Details* tab for the text
 in Transifex.
 
 Some strings will have **placeholders** in them to indicate that Alaveteli
@@ -115,7 +158,7 @@ translate the text that comes *after* the `|`.
 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
+even mySociety's release manager). If translators aren't technical, they can
 use Transifex without needing to worry about this.
 
 
@@ -125,3 +168,8 @@ 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/).
+
+If you are a developer or translator actively working on internationalising
+Alaveteli code, you should talk to us to find out when the next release is due,
+so your translations can be prepared in time to be included in it.
+
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