Document the weekly locale extraction process better (#2544)

README.md

@@ -241,6 +241,23 @@ module.exports = {
 };
 ```
 
+### Working on the documentation
+
+The documentation you are reading right now lives inside the source repository as
+[Github flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown).
+When you make changes to these files you can create a
+pull request to preview them or, better yet, you can use
+[grip](https://github.com/joeyespo/grip)
+to preview the changes locally.
+After installing `grip`, run it from the source directory like this:
+
+```
+grip .
+```
+
+Open its `localhost` URL and you will see the rendered `README.md` file.
+As you make edits, it will update automatically.
+
 ### Building and running services
 
 The following are scripts that are used in deployment - you generally won't

docs/i18n.md

@@ -6,12 +6,13 @@ carried out via [Pontoon](https://pontoon.mozilla.org/).
 Some commands wrap standard gettext tools. To run these commands you'll need
 to ensure you have done the following steps:
 
-* Run `yarn` to install all the project deps.
-* Install [gettext](https://www.gnu.org/software/gettext/) tools for your
-platform.
+* Run `yarn` to install all the project dependencies.
+* Install the [gettext](https://www.gnu.org/software/gettext/) tools for your
+platform and make sure they're on your `$PATH` by checking the output of
+`which gettext`.
 
-*NOTE: All the instructions below show `[MY_APP]` you should replace that with the
-name of the app you are updating e.g. `NODE_APP_INSTANCE=disco bin/create-locales`*
+*NOTE: All the instructions below show `[MY_APP]`; replace that with the
+name of the app you are updating, e.g. `NODE_APP_INSTANCE=disco bin/create-locales`*
 
 ## Adding a new language/locale
 
@@ -27,48 +28,128 @@ NODE_APP_INSTANCE=[MY_APP] NODE_PATH='./:./src' bin/create-locales
 
 ## Updating locales
 
-These docs detail the steps needing to be run to extract newly added strings
-and update the locales.
+Once a week right after the forthcoming release
+[is tagged](http://addons.readthedocs.io/en/latest/server/push-duty.html),
+the locales for each app must be generated.
 
-After running each process you will need to commit the changes and push a PR
-to the addons-frontend repo.
+This is a semi-automated process: a team member must create one pull
+request *per application* with the following commits:
+
+1. A commit containing the extraction of newly added strings
+2. A commit containing a merge of localizations
+3. A commit containing a newly generated debug locale
+
+Each one of these steps are detailed in the sections below. Let's begin...
 
 ### Extracting newly added strings
 
-Strings extracted are those wrapped with `i18n.gettext()` or any other
-function supported by Jed (the library we use in JavaScript to carry out
+Start the process by creating a git branch and extracting the locales for a
+given app. This uses `amo` as an example app but you would need to repeat the
+process in a new branch for `disco` and any other activate application
+(example: `NODE_APP_INSTANCE=disco ...`).
+
+```
+git checkout master
+git pull
+git checkout -b amo-locales
+NODE_APP_INSTANCE=amo bin/extract-locales
+```
+
+This extracts all strings wrapped with `i18n.gettext()` or any other
+function supported by [Jed][Jed] (the library we use in JavaScript to carry out
 replacements for the string keys in the current locale).
 
 The strings are extracted using a babel plugin via webpack. Extracted strings
 are added to a pot template file. This file is used to seed the po for each
 locale with the strings needing translating when merging locales.
 
-To extract + merge new strings for an app in the addons-frontend project
-you should run the following commands:
+Run `git diff` to see what the extraction did.
+**If no strings were updated then you do not have to continue creating the pull
+request. You can revert the changes made to the `pot` timestamp.**
+Here is an example of a diff where no strings were changed. It just shows
+a single change to the timestamp:
+
+```diff
+diff --git a/locale/templates/LC_MESSAGES/amo.pot b/locale/templates/LC_MESSAGES/amo.pot
+index 31e113f2..c7da4e34 100644
+--- a/locale/templates/LC_MESSAGES/amo.pot
++++ b/locale/templates/LC_MESSAGES/amo.pot
+@@ -2,7 +2,7 @@ msgid ""
+ msgstr ""
+ "Project-Id-Version: amo\n"
+ "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+-"POT-Creation-Date: 2017-06-08 14:01+0000\n"
++"POT-Creation-Date: 2017-06-08 14:43+0000\n"
+ "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+ "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+ "Language-Team: LANGUAGE <LL@li.org>\n"
+```
+
+When the application is under active development it's more likely that you will
+see a diff containing new strings or at least strings that have shifted to
+different line numbers in the source. If so, commit your change and continue
+to the next step:
 
 ```
-# First extract the new strings.
-NODE_APP_INSTANCE=[MY_APP] bin/extract-locales
-# Merge the new strings into the locale files.
-NODE_APP_INSTANCE=[MY_APP] bin/merge-locales
+git commit -a "Extract AMO locales"
+```
+
+### Merging locale files
+
+After extracting new strings, you have to merge them into the existing locale
+files. Do this in your branch and commit:
+
+```
+NODE_APP_INSTANCE=amo bin/merge-locales
+```
+
+Keep an eye out for
+[fuzzy strings](https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html)
+by running `git diff` and searching for a comment that looks like
+`# fuzzy`. This comment means the localization may not exactly match the source text;
+a localizer needs to review it.
+As per our configuration, the application will not display fuzzy translations. These
+strings will fall back to English.
+
+In some rare cases you may wish to remove the
+`fuzzy` marker to prevent falling back to English. Discuss it with a team
+member before removing `fuzzy` markers.
+
+Commit and continue to the next step:
+
+```
+git commit -a "Merged AMO locales"
 ```
 
 ### Building the debug locales
 
-Using this command Generates a unicode debug locale and a mirror rtl debug
+The next step is to generate a unicode debug locale and a mirror rtl debug
 locale using [potools](https://github.com/mozilla/potools/).
 
-To build the debug locale files run:
+Build the debug locale and commit it to your branch:
 
 ```
-# build the debug locale files.
-NODE_APP_INSTANCE=[MY_APP] bin/debug-locales
+NODE_APP_INSTANCE=amo bin/debug-locales
+git commit -a "Generated AMO debug locale"
 ```
 
+### Finalizing the extract/merge process
+
+Now that you have extracted, merged, and generated a debug locale for one
+application, it's time to create a pull request for your branch. For example:
+
+```
+git push origin amo-locales
+```
+
+Request a review for the pull request and merge it like any other.
+If necessary, repeat the process for the next application.
+
 ### Building the JS locale files
 
-This command create the JSON files which are then built into JS bundles by
-webpack when the build step is run.
+This command creates the JSON files which are then built into JS bundles by
+webpack when the build step is run. This happens automatically as part of
+the deployment process.
 
 Since dist files are created when needed you only need to build and commit
 the JSON to the repo.
@@ -85,7 +166,7 @@ about.
 
 ### Jed
 
-We use [Jed](https://slexaxton.github.io/Jed/) as the API for providing
+We use [Jed][Jed] as the API for providing
 `gettext` functions inside React components. An initialized `Jed` instance
 has all the `gettext` related functionality exposed as methods. There is a
 fancy chained API but we've stuck to a more traditional approach.
@@ -139,7 +220,7 @@ That's pretty much all there is to it.
 ## Using the Jed API
 
 Once you have `i18n` available to your component you can then use
-any of the Jed methods exposed on the `i18n` object.
+any of the [Jed][Jed] methods exposed on the `i18n` object.
 
 ```javascript
 gettext = function ( key )
@@ -209,3 +290,5 @@ You can also use DOMPurify to sanitize strings that may contain HTML
 following substitutions so that anything not explicitly allowed is removed.
 DOMPurify will also help protect against malformed HTML in case opening
 and closing tag substitutions vars get swapped around inadvertently.
+
+[Jed]: https://slexaxton.github.io/Jed/