diff --git a/Design:-i18n.md b/Design:-i18n.md
new file mode 100644
index 0000000..78840f2
--- /dev/null
+++ b/Design:-i18n.md
@@ -0,0 +1,62 @@
+# Internationalization
+
+We are using the [i18next](http://i18next.com/) library for NLS support in both the runtime and editor.
+
+### Core Message Catalogs
+
+| Component | Namespace  | Location                                             |
+|-----------|------------|------------------------------------------------------|
+| Runtime   | `runtime`  | `node-red/locales/__lang__/runtime.json`             |
+| Editor    | `editor`   | `node-red/locales/__lang__/editor.json`              |
+| Core nodes| `node-red` | `node-red/nodes/core/locales/__lang__/messages.json` |
+
+
+### Node Modules Catalogs
+
+A node module provides message catalogs on a per-node-set basis. Given a node-set identified in package.json as:
+
+    "node-red": {
+        "myNode": "lib/my-node.js"
+    }
+
+The following message catalogs may exist:
+
+    lib/locales/__lang__/my-node.json
+    lib/locales/__lang__/my-node.html
+
+**NB**: the locales directory is relative to the node's `.js` file.
+
+The `.json` file is the message catalog for both runtime and editor.
+
+The `.html` file contains the localized node help content. The help content in the top-level `.html` file _may_ identify what language it provides using a `data-lang` attribute: (`en-US` assumed if not set).
+
+    <script type="text/x-red" data-help-name="foo" data-lang="en-US">
+        <p>A foo node</p>
+    </script>
+
+The catalog for a node-set is added under the namespace `<module>/<set>`.
+
+## Loading catalogs in the editor
+
+A new api end-point is added to load message catalogs:
+
+    /locales/__lang__/__namespace__.json
+
+## Using i18n for messages
+
+### Core Runtime
+
+    var i18n = require("./path/to/i18n.js");
+    // i18n._ is provided as a wrapper to i18next.t
+
+    // Retrieve the value of the message `runtime.version`
+    console.log(i18n._("runtime.version"));
+
+    // Retrieve the value of the message `example.insert" with a named insert
+    //   "example.insert" : "I have a value of __myValue__"
+    console.log(i18n._("example.insert",{myValue: 123});
+
+### Nodes
+
+Nodes can use `RED._()` to retrieve messages. The function they are provided is pre-scoped to the node's own namespace so they don't have to worry about providing it with each message.
+