Stabilize message, new option, switch to defineMessages

This stabilizes the `defaultMessage` by parsing and pretty-printing
it; this removes any insignificant whitespace, and should yield less
false-positive re-translations.

This adds a new `enforceDescriptions` option to require that all
declared messages _must_ contain a `description` for translators.

The `description` field will now _always_ be removed from the source
code to save k-weight.

This also switches from `defineMessage` to the new `defineMessages`.

Author: ericf

README.md

@@ -21,13 +21,18 @@ $ npm install babel-plugin-react-intl
   "plugins": ["react-intl"],
   "extra": {
     "react-intl": {
-        "messagesDir": "./build/messages/"
+        "messagesDir": "./build/messages/",
+        "enforceDescriptions": true
     }
   }
 }
 ```
 
-The `messagesDir` option is the target location where the plugin will output a `.json` file corresponding to each component from which React Intl messages were extracted.
+#### Options
+
+- **`messagesDir`**: The target location where the plugin will output a `.json` file corresponding to each component from which React Intl messages were extracted.
+
+- **`enforceDescriptions`**: Whether or not message declarations _must_ contain a `description` to provide context to translators.
 
 ### Via CLI
 

package.json

@@ -11,6 +11,7 @@
   "author": "Eric Ferraiuolo <edf@ericf.me>",
   "dependencies": {
     "babel-runtime": "^5.8.20",
+    "intl-messageformat-parser": "^1.1.0",
     "mkdirp": "^0.5.1"
   },
   "devDependencies": {

src/index.js

@@ -7,47 +7,27 @@
 import * as p from 'path';
 import {writeFileSync} from 'fs';
 import {sync as mkdirpSync} from 'mkdirp';
+import printICUMessage from './print-icu-message';
 
 const COMPONENT_NAMES = [
     'FormattedMessage',
     'FormattedHTMLMessage',
 ];
 
 const FUNCTION_NAMES = [
-    'defineMessage',
+    'defineMessages',
 ];
 
 const IMPORTED_NAMES   = new Set([...COMPONENT_NAMES, ...FUNCTION_NAMES]);
 const DESCRIPTOR_PROPS = new Set(['id', 'description', 'defaultMessage']);
 
-export default function ({Plugin}) {
-    function getModuleSourceName(options) {
-        const reactIntlOptions = options.extra['react-intl'] || {};
-        return reactIntlOptions.moduleSourceName || 'react-intl';
-    }
-
-    function getMessagesDir(options) {
-        const reactIntlOptions = options.extra['react-intl'] || {};
-        return reactIntlOptions.messagesDir;
+export default function ({Plugin, types: t}) {
+    function getReactIntlOptions(options) {
+        return options.extra['react-intl'] || {};
     }
 
-    function getMessageDescriptor(propertiesMap) {
-        // Force property order on descriptors.
-        let descriptor = [...DESCRIPTOR_PROPS].reduce((descriptor, key) => {
-            descriptor[key] = undefined;
-            return descriptor;
-        }, {});
-
-        for (let [key, value] of propertiesMap) {
-            key = getMessageDescriptorKey(key);
-
-            if (DESCRIPTOR_PROPS.has(key)) {
-                // TODO: Should this be trimming values?
-                descriptor[key] = getMessageDescriptorValue(value).trim();
-            }
-        }
-
-        return descriptor;
+    function getModuleSourceName(options) {
+        return getReactIntlOptions(options).moduleSourceName || 'react-intl';
     }
 
     function getMessageDescriptorKey(path) {
@@ -84,9 +64,38 @@ export default function ({Plugin}) {
         );
     }
 
-    function storeMessage(descriptor, node, file) {
-        const {id}       = descriptor;
-        const {messages} = file.get('react-intl');
+    function createMessageDescriptor(propPaths) {
+        return propPaths.reduce((hash, [keyPath, valuePath]) => {
+            let key = getMessageDescriptorKey(keyPath);
+
+            if (DESCRIPTOR_PROPS.has(key)) {
+                let value = getMessageDescriptorValue(valuePath).trim();
+
+                if (key === 'defaultMessage') {
+                    try {
+                        hash[key] = printICUMessage(value);
+                    } catch (e) {
+                        throw valuePath.errorWithNode(
+                            `[React Intl] Message failed to parse: ${e} ` +
+                            'See: http://formatjs.io/guides/message-syntax/'
+                        );
+                    }
+                } else {
+                    hash[key] = value;
+                }
+            }
+
+            return hash;
+        }, {});
+    }
+
+    function createPropNode(key, value) {
+        return t.property('init', t.literal(key), t.literal(value));
+    }
+
+    function storeMessage({id, description, defaultMessage}, node, file) {
+        const {enforceDescriptions} = getReactIntlOptions(file.opts);
+        const {messages}            = file.get('react-intl');
 
         if (!id) {
             throw file.errorWithNode(node,
@@ -95,22 +104,35 @@ export default function ({Plugin}) {
         }
 
         if (messages.has(id)) {
-            throw file.errorWithNode(node,
-                `[React Intl] Duplicate message id: "${id}"`
-            );
+            let existing = messages.get(id);
+
+            if (description !== existing.description ||
+                defaultMessage !== existing.defaultMessage) {
+
+                throw file.errorWithNode(node,
+                    `[React Intl] Duplicate message id: "${id}", ` +
+                    'but the `description` and/or `defaultMessage` are different.'
+                );
+            }
         }
 
-        if (!descriptor.defaultMessage) {
+        if (!defaultMessage) {
             let {loc} = node;
             file.log.warn(
                 `[React Intl] Line ${loc.start.line}: ` +
-                `Message "${id}" is missing a \`defaultMessage\` ` +
-                `and will not be extracted.`
+                'Message is missing a `defaultMessage` and will not be extracted.'
             );
+
             return;
         }
 
-        messages.set(id, descriptor);
+        if (enforceDescriptions && !description) {
+            throw file.errorWithNode(node,
+                '[React Intl] Message must have a `description`.'
+            );
+        }
+
+        messages.set(id, {id, description, defaultMessage});
     }
 
     function referencesImport(path, mod, importedNames) {
@@ -147,7 +169,7 @@ export default function ({Plugin}) {
 
                 exit(node, parent, scope, file) {
                     const {messages}  = file.get('react-intl');
-                    const messagesDir = getMessagesDir(file.opts);
+                    const {messagesDir} = getReactIntlOptions(file.opts);
                     const {basename, filename} = file.opts;
 
                     let descriptors = [...messages.values()];
@@ -170,46 +192,79 @@ export default function ({Plugin}) {
 
             JSXOpeningElement(node, parent, scope, file) {
                 const moduleSourceName = getModuleSourceName(file.opts);
+
                 let name = this.get('name');
 
                 if (referencesImport(name, moduleSourceName, COMPONENT_NAMES)) {
                     let attributes = this.get('attributes')
-                        .filter((attr) => attr.isJSXAttribute())
-                        .map((attr) => [attr.get('name'), attr.get('value')]);
+                        .filter((attr) => attr.isJSXAttribute());
 
-                    let descriptor = getMessageDescriptor(new Map(attributes));
+                    let descriptor = createMessageDescriptor(
+                        attributes.map((attr) => [
+                            attr.get('name'),
+                            attr.get('value'),
+                        ])
+                    );
 
                     // In order for a default message to be extracted when
                     // declaring a JSX element, it must be done with standard
                     // `key=value` attributes. But it's completely valid to
                     // write `<FormattedMessage {...descriptor} />`, because it
-                    // will be skipped here and extracted elsewhere.
-                    if (descriptor.id) {
+                    // will be skipped here and extracted elsewhere. When
+                    // _either_ an `id` or `defaultMessage` prop exists, the
+                    // descriptor will be checked; this way mixing an object
+                    // spread with props will fail.
+                    if (descriptor.id || descriptor.defaultMessage) {
                         storeMessage(descriptor, node, file);
+
+                        attributes
+                            .filter((attr) => {
+                                let keyPath = attr.get('name');
+                                let key = getMessageDescriptorKey(keyPath);
+                                return key === 'description';
+                            })
+                            .forEach((attr) => attr.dangerouslyRemove());
                     }
                 }
             },
 
             CallExpression(node, parent, scope, file) {
                 const moduleSourceName = getModuleSourceName(file.opts);
 
-                let callee = this.get('callee');
-
-                if (referencesImport(callee, moduleSourceName, FUNCTION_NAMES)) {
-                    let messageArg = this.get('arguments')[0];
-                    if (!(messageArg && messageArg.isObjectExpression())) {
+                function processMessageObject(messageObj) {
+                    if (!(messageObj && messageObj.isObjectExpression())) {
                         throw file.errorWithNode(node,
                             `[React Intl] \`${callee.node.name}()\` must be ` +
                             `called with message descriptor defined via an ` +
                             `object expression.`
                         );
                     }
 
-                    let properties = messageArg.get('properties')
-                        .map((prop) => [prop.get('key'), prop.get('value')]);
+                    let properties = messageObj.get('properties');
+
+                    let descriptor = createMessageDescriptor(
+                        properties.map((prop) => [
+                            prop.get('key'),
+                            prop.get('value'),
+                        ])
+                    );
 
-                    let descriptor = getMessageDescriptor(new Map(properties));
                     storeMessage(descriptor, node, file);
+
+                    messageObj.replaceWith(t.objectExpression([
+                        createPropNode('id', descriptor.id),
+                        createPropNode('defaultMessage', descriptor.defaultMessage),
+                    ]));
+                }
+
+                let callee = this.get('callee');
+
+                if (referencesImport(callee, moduleSourceName, FUNCTION_NAMES)) {
+                    let firstArg = this.get('arguments')[0];
+
+                    firstArg.get('properties')
+                        .map((prop) => prop.get('value'))
+                        .forEach(processMessageObject);
                 }
             },
         },

src/print-icu-message.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2015, Yahoo Inc.
+ * Copyrights licensed under the New BSD License.
+ * See the accompanying LICENSE file for terms.
+ */
+
+import {parse} from 'intl-messageformat-parser';
+
+export default function (message) {
+    let ast = parse(message);
+    return printICUMessage(ast);
+}
+
+function printICUMessage(ast) {
+    let printedNodes = ast.elements.map((node) => {
+        if (node.type === 'messageTextElement') {
+            return node.value;
+        }
+
+        if (!node.format) {
+            return `{${node.id}}`;
+        }
+
+        switch (getArgumentType(node.format.type)) {
+        case 'number':
+        case 'date':
+        case 'time':
+            return printSimpleFormatASTNode(node);
+
+        case 'plural':
+        case 'selectordinal':
+        case 'select':
+            return printOptionalFormatASTNode(node);
+        }
+    });
+
+    return printedNodes.join('');
+}
+
+function getArgumentType(astType) {
+    return astType.replace(/Format$/, '').toLowerCase();
+}
+
+function printSimpleFormatASTNode(node) {
+    let {id, format} = node;
+    let argumentType = getArgumentType(format.type);
+    let style = format.style ? `, ${format.style}` : '';
+
+    return `{${id}, ${argumentType}${style}}`;
+}
+
+function printOptionalFormatASTNode(node) {
+    let {id, format} = node;
+    let argumentType = getArgumentType(format.type);
+    let offset = format.offset ? `, offset:${format.offset}` : '';
+
+    let options = format.options.map((option) => {
+        let optionValue = printICUMessage(option.value);
+        return ` ${option.selector} {${optionValue}}`;
+    });
+
+    return `{${id}, ${argumentType}${offset},${options.join('')}}`;
+}