Add functionality to update comments (#8)

Implements comment pushing mode, with documentation.

Author: Eric Fischer

README.md

@@ -1,13 +1,45 @@
 # reactifex
 
+Helper utility designed to make it easy to upload react-intl extracted messages to transifex, with support for ICU plurals and translator comments.
+
 [![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](reactifex)
 [![license](https://img.shields.io/npm/l/reactifex.svg)](reactifex)
 [![npm_version](https://img.shields.io/npm/v/reactifex.svg)](reactifex)
 [![Build Status](https://travis-ci.org/efischer19/reactifex.svg?branch=master)](https://travis-ci.org/efischer19/reactifex)
 
-Helper utility designed to make it easy to upload react-intl extracted messages to transifex, with support for ICU plurals and translator comments.
+
+There are two modes of usage - compilation and comment pushing.
+
+## Compilation mode
+
+In this mode, messages that have been extracted by `babel-plugin-react-intl` (into individual files) are combined. The resulting json is suitable to upload to Transifex and matches their specified `KEYVALUEJSON` format.
 
 usage: `$(npm bin)/reactifex <input_folder> <output_file>`
   - `input_folder` corresponds to the `messagesDir` option used by `babel-plugin-react-intl`
     - note that reactifex assumes folder structure based on this default
   - `output_file` will be suitable for upload to transifex
+
+## Comment pushing
+
+This mode is why I wrote this library in the first place - I wanted the ability to use comments as `PO` files do, but none of the tools I found to convert react-intl messages to `PO` files were able to properly handle ICU pluralization. By keeping everything in a js context with `KEYVALUEJSON`, plurals work correctly *and* we now have comment support for translators (by default, Transifex's `KEYVALUEJSON` file format does not allow for comments to be included with strings for translation).
+
+Note that tests for this mode aren't included, as it relies on Transifex's API being up and responsive.
+
+Usage is a little complicated, I'm sorry about that; you're going to be running this server-side as a series of bash commands. Do note that I assume `$SECRET_USER` and `$SECRET_PWD` env vars exist for basic auth purposes. See [Transifex's API Introduction](https://docs.transifex.com/api/introduction) for more details on authentication. Here's an example, written as it would be in the Makefile of a project that makes use of reactifex:
+
+```
+tx_url1 = https://www.transifex.com/api/2/project/<project>/resource/<resource>/translation/<default_language_code>/strings/
+tx_url2 = https://www.transifex.com/api/2/project/<project>/resource/<resource>/source/
+push_translations:
+    ./node_modules/reactifex/bash_scripts/get_hashed_strings.sh $(tx_url1)
+    $$(npm bin)/reactifex <input_folder> --comments
+    ./node_modules/reactifex/bash_scripts/put_comments.sh $(tx_url2)
+```
+
+  - [tx_url1](https://docs.transifex.com/api/translation-strings#identifying-strings-using-hashes) and [tx_url2](https://docs.transifex.com/api/resource-strings) are just variables as defined by the Transifex API documentation, extracted for readability.
+
+  - First, `bash_scripts/get_hashed_strings.sh` is called with a url argument. This will populate `bash_scripts/hashmap.json` with data about the strings in your resource, including the all-important `string_hash`.
+
+  - Next, the main reactifex script (node js) runs with an additional `--comments` flag, and no output file. This has the effect of gathering up all your `babel-plugin-react-intl` extracted messages *with* their comments attached. From there, it's simple enough to match up each message with its `string_hash`, and makes it possible to generate `bash_scripts/put_comments.sh` (a series of curl requests, one per message)
+
+  - Finally, `bash_scripts/put_comments.sh` is run with the base PUT url as an argument (we generated the specific `string_hash` portion in the previous step), updating translator comments for each message on Transifex via their API.

bash_scripts/get_hashed_strings.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+curl -L --user $SECRET_USER:$SECRET_PWD -X GET $1 > $(dirname $0)/hashmap.json

bash_scripts/hashmap.json

@@ -0,0 +1 @@
+#!/bin/bash

bash_scripts/put_comments.sh

@@ -19,4 +19,26 @@ var outData = {};
 inData.forEach((message) => {
   outData[message["id"]] = message["defaultMessage"];
 });
-fs.writeFileSync(process.argv[3], JSON.stringify(outData, null, 2));
+
+if (process.argv[3] === "--comments") {
+  process.stdout.write("generating bash scripts...\n");
+  var messageInfo = JSON.parse(fs.readFileSync(__dirname + "/bash_scripts/hashmap.json"));
+  var scriptPath = __dirname + "/bash_scripts/put_comments.sh";
+  fs.writeFileSync(scriptPath, "#!/bin/bash\n");
+  fs.writeFileSync(scriptPath, "set -x\n");
+  inData.forEach((message) => {
+    var info = messageInfo.find(mi => mi.key == message.id);
+    if (info) {
+      var header = " -H \"Content-Type: application/json\"";
+      var escapedDescription = message.description.replace(/(["])/g, "\\\\\\$1");
+      var data = " --data \"{\\\"comment\\\": \\\"" + escapedDescription + "\\\"}\"";
+      var url = " $1" + info.string_hash;
+      fs.appendFileSync(scriptPath, "curl -L -w \"\\n\" --user $SECRET_USER:$SECRET_PWD -X PUT" + header + data + url + "\n");
+    } else {
+      process.stdout.write("string " + message.id + " does not yet exist on transifex!\n");
+    }
+  });
+  fs.writeFileSync(scriptPath, "set +x\n");
+} else {
+  fs.writeFileSync(process.argv[3], JSON.stringify(outData, null, 2));
+}

main.js

@@ -1,6 +1,6 @@
 {
   "name": "reactifex",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "description": "A helper for moving react-intl messages to transifex and back",
   "bin": "./main.js",
   "scripts": {