Add docs for i18n and unify debug-locales to run per app

bin/create-locales

@@ -1,47 +1,52 @@
 #!/usr/bin/env node --use_strict
+/* eslint-disable no-console */
 
 /*
  * If a locale doesn't exist create it under locale and generate
  * the relevant po files from the .pot
  */
 
+require('babel-register');
+
+
+const chalk = require('chalk');
 const config = require('config');
 const fs = require('fs');
-const glob = require('glob');
 const path = require('path');
 const shell = require('shelljs');
 
 const supportedLangs = config.get('langs');
 const localeDir = path.join(__dirname, '../locale');
 const templateDir = path.join(localeDir, 'templates/LC_MESSAGES');
-const potFiles = glob.sync(`${templateDir}/*.pot`);
-
-require('babel-register');
 const langToLocale = require('../src/core/i18n/utils').langToLocale;
 
+const appName = config.get('appName');
+
+if (!appName) {
+  console.log(
+    chalk.red('Please specify the appName with NODE_APP_INSTANCE'));
+  process.exit(1);
+}
+
+
 let lang;
 let locale;
-let potFile;
-let fileName;
 let outputFile;
 
 for (lang of supportedLangs) {
   locale = langToLocale(lang);
   shell.exec(`mkdir -p ${localeDir}/${locale}/LC_MESSAGES/`);
-  for (potFile of potFiles) {
-    fileName = path.basename(potFile, '.pot');
-    outputFile = path.join(localeDir, locale, 'LC_MESSAGES', `${fileName}.po`);
-    try {
-      fs.statSync(outputFile);
-      // eslint-disable-next-line no-console
-      console.log(`${outputFile} already exists skipping`);
-    } catch (e) {
-      if (e.code === 'ENOENT') {
-        shell.exec(`msginit --no-translator --input=${templateDir}/${fileName}.pot
-                    --output-file=${outputFile} -l ${locale}`.replace('\n', ' '));
-      } else {
-        throw e;
-      }
+  outputFile = path.join(localeDir, locale, 'LC_MESSAGES', `${appName}.po`);
+  try {
+    fs.statSync(outputFile);
+    // eslint-disable-next-line no-console
+    console.log(`${outputFile} already exists skipping`);
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      shell.exec(`msginit --no-translator --input=${templateDir}/${appName}.pot
+                  --output-file=${outputFile} -l ${locale}`.replace('\n', ' '));
+    } else {
+      throw e;
     }
   }
 }

bin/debug-locales

@@ -1,4 +1,5 @@
 #!/usr/bin/env node --use_strict
+/* eslint-disable no-console */
 
 /*
  * Generate a unicode debug locale and a flipped rtl
@@ -12,27 +13,32 @@
  *   sudo apt-get install translate-toolkit
  *
  */
+require('babel-register');
 
-const glob = require('glob');
 const path = require('path');
 const shell = require('shelljs');
 
+const chalk = require('chalk');
 const debugLocales = ['dbl', 'dbr'];
+const config = require('config');
 const localeDir = path.join(__dirname, '../locale');
 const templateDir = path.join(localeDir, 'templates/LC_MESSAGES');
-const potFiles = glob.sync(`${templateDir}/*.pot`);
+const appName = config.get('appName');
+
+if (!appName) {
+  console.log(
+    chalk.red('Please specify the appName with NODE_APP_INSTANCE'));
+  process.exit(1);
+}
 
 let locale;
 let rewrite;
 let potFile;
 let poFile;
-let fileName;
 
 for (locale of debugLocales) {
-  for (potFile of potFiles) {
-    fileName = path.basename(potFile, '.pot');
-    poFile = path.join(localeDir, locale, 'LC_MESSAGES', `${fileName}.po`);
-    rewrite = locale === 'dbl' ? 'unicode' : 'flipped';
-    shell.exec(`podebug -i ${potFile} -o ${poFile} --rewrite ${rewrite}`);
-  }
+  potFile = path.join(templateDir, `${appName}.pot`);
+  poFile = path.join(localeDir, locale, 'LC_MESSAGES', `${appName}.po`);
+  rewrite = locale === 'dbl' ? 'unicode' : 'flipped';
+  shell.exec(`podebug -i ${potFile} -o ${poFile} --rewrite ${rewrite}`);
 }

docs/i18n.md

@@ -0,0 +1,86 @@
+# Internationalization (i18n)
+
+We're using gettext for translations. All the actual translations are
+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 `npm install` to install all the project deps.
+* Install [gettext](https://www.gnu.org/software/gettext/) tools for your
+platform.
+* Install podebug (see [Building the debug locales for more information](#build-the-debug-locales))
+
+*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`*
+
+## Adding a new language/locale
+
+The supported languages are defined in the configuration. See
+[`config/default.js`](https://bit.ly/1XScjwq) and look for the `langs` list.
+
+Add the new language to the list and then run:
+
+```
+# create the locale for a newly added language.
+NODE_APP_INSTANCE=[MY_APP] bin/create-locales
+```
+
+## Updating locales
+
+These docs detail the steps needing to be run to extract newly added strings
+and update the locales.
+
+After running each process you will need to commit the changes and push a PR
+to the addons-frontend repo.
+
+### 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
+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:
+
+```
+# 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
+```
+
+### Building the debug locales
+
+Using this command Generates a unicode debug locale and a flipped rtl debug
+locale using [podebug](https://bit.ly/1r3yFy5).
+
+`podebug` is required for this step, you can install it with:
+
+ * OSX: `brew install translate-toolkit`
+ * Debian Linux variants: `sudo apt-get install translate-toolkit`
+ * For other platforms see the [podebug docs](https://bit.ly/1r3yFy5)
+
+To build the debug locale files run:
+
+```
+# build the debug locale files.
+NODE_APP_INSTANCE=[MY_APP] bin/debug-locales
+```
+
+### Building the JSON locale files
+
+This command create the JSON files which are then built into JS bundles by
+webpack when the build step is run.
+
+Since dist files are created when needed you only need to build and commit
+the JSON to the repo.
+
+```
+# build the JSON.
+NODE_APP_INSTANCE=[MY_APP] bin/build-locales
+```

docs/index.md

@@ -2,3 +2,4 @@ addons-frontend
 ===============
 
 * [How to Add a Page](./adding-a-page.md)
+* [Internationalization (i18n)](./i18n.md)