Release v0.2.7

add reverse method of extract(string)

.npmignore

@@ -2,3 +2,6 @@
 /dist
 /Gruntfile.coffee
 /test
+/.jshintrc
+/.travis.yml
+/bower.json

.travis.yml

@@ -3,5 +3,5 @@ node_js:
   - "0.8"
   - "0.10"
   - "0.11"
-before_script:
+before_install:
   - npm install -g grunt-cli

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2013 Ruben Vermeersch
+Copyright (C) 2013-2014 Ruben Vermeersch
 Copyright (C) 2012 Michael Holly
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of

README.md

@@ -1,22 +1,165 @@
-Used to load and save PO files.
+# pofile - gettext .po parsing for JavaScript
+
+> Parse and serialize Gettext PO files.
+
+[![Build Status](https://travis-ci.org/rubenv/pofile.png?branch=master)](https://travis-ci.org/rubenv/pofile)
+
+## Usage
+Add pofile to your project:
+
+### Installation (Node.JS, browser via Browserified)
+```
+npm install --save pofile
+```
+
+Reference it in your code:
 
 ```js
 var PO = require('pofile');
+```
 
+### Installation (via bower)
+```
+bower install --save pofile
+```
+
+Add it to your HTML file:
+
+```html
+<script src="bower_components/pofile/dist/pofile.js"></script>
+```
+
+Reference it in your code:
+
+```js
+var PO = require('pofile');
+```
+
+### Loading and parsing
+
+You can create a new empty PO file by using the class:
+
+```js
+var po = new PO();
+```
+
+Or by loading a file (Node.JS only):
+
+```js
 PO.load('text.po', function (err, po) {
     // Handle err if needed
-    console.log(po.headers);
-    console.log(po.items);
-  
-    po.save('copy.po', function (err) {
-        // Handle err if needed
-        console.log('We copied a PO file for no reason!');
-    });
+    // Do things with po
 });
 ```
 
+Or by parsing a string:
+
+```js
+var po = PO.parse(myString);
+```
+
+### The PO class
+
+The `PO` class exposes three members:
+
+* `comments`: An array of comments (found at the header of the file).
+* `headers`: A dictionary of the headers.
+* `items`: An array of `PO.Item` objects, each of which represents a string
+  from the gettext catalog.
+
+There are two methods available:
+
+* `save`: Accepts a filename and callback, writes the po file to disk.
+
+```js
+po.save('out.po', function (err) {
+    // Handle err if needed
+});
+```
+
+* `toString`: Serializes the po file to a string.
+
+### The PO.Item class
+
+The `PO` class exposes the following members:
+
+* `msgid`: The message id.
+* `msgid_plural`: The plural message id (null if absent).
+* `msgstr`: An array of translated strings. Items that have no plural msgid
+  only have one element in this array.
+* `references`: An array of reference strings.
+* `comments`: An array of string translator comments.
+* `extractedComments`: An array of string extracted comments.
+* `flags`: A dictionary of the string flags. Each flag is mapped to a key with
+  value true. For instance, a string with the fuzzy flag set will have
+  `item.flags.fuzzy == true`.
+* `msgctxt`: Context of the message, an arbitrary string, can be used for disambiguation.
+
+
+## Contributing
+
+In lieu of a formal styleguide, take care to maintain the existing coding
+style. Add unit tests for any new or changed functionality. Lint and test your
+code using [Grunt](http://gruntjs.com/).
+
 ## Credits
 
-  Originally based on node-po (written by Michael Holly). Rebranded because
-  node-po is unmaintained and because this library is no longer limited to
-  Node.JS: it works in the browser too.
+Originally based on node-po (written by Michael Holly). Rebranded because
+node-po is unmaintained and because this library is no longer limited to
+Node.JS: it works in the browser too.
+
+### Changes compared to node-po
+
+* Proper handling of async methods that won't crash your Node.JS process when
+  something goes wrong.
+* Support for parsing string flags (e.g. fuzzy).
+* A test suite.
+* Browser support (through Browserified and bower).
+
+### Migrating from node-po
+
+You'll need to update the module reference: `require('pofile')` instead of
+`require('node-po')`.
+
+At the initial release, node-po and pofile have identical APIs, with one small
+exception: the `save` and `load` methods now take a callback that has an `err`
+parameter: `(err)` for `save` and `(err, po)` for `load`. This is similar to
+Node.JS conventions.
+
+Change code such as:
+
+```js
+PO.load('text.po', function (po) {
+```
+
+To:
+
+```js
+PO.load('text.po', function (err, po) {
+    // Handle err if needed
+```
+
+## License 
+
+    (The MIT License)
+
+    Copyright (C) 2013-2014 by Ruben Vermeersch <ruben@rocketeer.be>
+    Copyright (C) 2012 by Michael Holly
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "pofile",
-  "version": "0.2.0",
+  "version": "0.2.7",
   "authors": [
     "Ruben Vermeersch <ruben@rocketeer.be>"
   ],

dist/pofile.js

@@ -1,4 +1,4 @@
-require=(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);throw new Error("Cannot find module '"+o+"'")}var f=n[o]={exports:{}};t[o][0].call(f.exports,function(e){var n=t[o][1][e];return s(n?n:e)},f,f.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({"GPUdqu":[function(require,module,exports){
+require=(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);throw new Error("Cannot find module '"+o+"'")}var f=n[o]={exports:{}};t[o][0].call(f.exports,function(e){var n=t[o][1][e];return s(n?n:e)},f,f.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({"W8CkM0":[function(require,module,exports){
 var fs = require('fs'),
     isArray = require('lodash.isarray');
 
@@ -90,12 +90,15 @@ PO.parse = function (data) {
 
     var item = new PO.Item(),
         context = null,
-        plural = 0;
+        plural = 0,
+        obsolete = false;
 
     function finish() {
         if (item.msgid.length > 0) {
             po.items.push(item);
             item = new PO.Item();
+            item.obsolete = obsolete;
+            obsolete = false;
         }
     }
 
@@ -110,6 +113,14 @@ PO.parse = function (data) {
     while (lines.length > 0) {
         var line = trim(lines.shift()),
             add = false;
+
+        if (line.match(/^#\~/)) { // Obsolete item
+            obsolete = true;
+            line = trim(line.substring(2));
+        } else {
+            obsolete = false;
+        }
+
         if (line.match(/^#:/)) { // Reference
             finish();
             item.references.push(trim(line.replace(/^#:/, '')));
@@ -121,9 +132,13 @@ PO.parse = function (data) {
                 item.flags[flags[i]] = true;
             }
         }
-        else if (line.match(/^#/)) { // Comment
+        else if (line.match(/^#\s+/)) { // Translator comment
             finish();
-            item.comments.push(trim(line.replace(/^#/, '')));
+            item.comments.push(trim(line.replace(/^#\s+/, '')));
+        }
+        else if (line.match(/^#\./)) { // Extracted comment
+            finish();
+            item.extractedComments.push(trim(line.replace(/^#\./, '')));
         }
         else if (line.match(/^msgid_plural/)) { // Plural form
             item.msgid_plural = extract(line);
@@ -140,6 +155,10 @@ PO.parse = function (data) {
             item.msgstr[plural] = extract(line);
             context = 'msgstr';
         }
+        else if (line.match(/^msgctxt/)) { // Context
+            finish();
+            item.msgctxt = extract(line);
+        }
         else { // Probably multiline string or blank
             if (line.length > 0) {
                 if (context === 'msgstr') {
@@ -161,17 +180,26 @@ PO.parse = function (data) {
 
 PO.Item = function () {
     this.msgid = '';
+    this.msgctxt = null;
     this.references = [];
     this.msgid_plural = null;
     this.msgstr = [];
-    this.comments = [];
+    this.comments = []; // translator comments
+    this.extractedComments = [];
     this.flags = {};
+    this.obsolete = false;
 };
 
 PO.Item.prototype.toString = function () {
     var lines = [],
         that = this;
 
+    // reverse what extract(string) method during PO.parse does
+    var _escape = function (string) {
+        string = string.replace(/\\/g, '\\\\');
+        return string.replace(/"/g, '\\"');
+    };
+
     var _process = function (keyword, text, i) {
         var lines = [],
             parts = text.split(/\n/),
@@ -179,27 +207,36 @@ PO.Item.prototype.toString = function () {
         if (parts.length > 1) {
             lines.push(keyword + index + ' ""');
             parts.forEach(function (part) {
-                lines.push('"' + part + '"');
+                lines.push('"' + _escape(part) + '"');
             });
         }
         else {
-            lines.push(keyword + index + ' "' + text + '"');
+            lines.push(keyword + index + ' "' + _escape(text) + '"');
         }
         return lines;
     };
 
-    if (this.references.length > 0) {
-        this.references.forEach(function (ref) {
-            lines.push('#: ' + ref);
-        });
-    }
+    // https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
+    // says order is translator-comments, extracted-comments, references, flags
+
+    this.comments.forEach(function (c) {
+        lines.push('# ' + c);
+    });
+
+    this.extractedComments.forEach(function (c) {
+        lines.push('#. ' + c);
+    });
+
+    this.references.forEach(function (ref) {
+        lines.push('#: ' + ref);
+    });
 
     var flags = Object.keys(this.flags);
     if (flags.length > 0) {
         lines.push('#, ' + flags.join(","));
     }
 
-    ['msgid', 'msgid_plural', 'msgstr'].forEach(function (keyword) {
+    ['msgctxt', 'msgid', 'msgid_plural', 'msgstr'].forEach(function (keyword) {
         var text = that[keyword];
         if (text != null) {
             if (isArray(text) && text.length > 1) {
@@ -214,13 +251,17 @@ PO.Item.prototype.toString = function () {
         }
     });
 
-    return lines.join("\n");
+    if (this.obsolete) {
+        return "#~ " + lines.join("\n#~ ");
+    } else {
+        return lines.join("\n");
+    }
 };
 
 module.exports = PO;
 
 },{"fs":3,"lodash.isarray":4}],"pofile":[function(require,module,exports){
-module.exports=require('GPUdqu');
+module.exports=require('W8CkM0');
 },{}],3:[function(require,module,exports){
 
 },{}],4:[function(require,module,exports){
@@ -306,4 +347,4 @@ function isNative(value) {
 
 module.exports = isNative;
 
-},{}]},{},["GPUdqu"])
+},{}]},{},["W8CkM0"])

dist/pofile.min.js

@@ -1 +1 @@
-require=function a(b,c,d){function e(g,h){if(!c[g]){if(!b[g]){var i="function"==typeof require&&require;if(!h&&i)return i(g,!0);if(f)return f(g,!0);throw new Error("Cannot find module '"+g+"'")}var j=c[g]={exports:{}};b[g][0].call(j.exports,function(a){var c=b[g][1][a];return e(c?c:a)},j,j.exports,a,b,c,d)}return c[g].exports}for(var f="function"==typeof require&&require,g=0;g<d.length;g++)e(d[g]);return e}({GPUdqu:[function(a,b){function c(a){return a.replace(/^\s+|\s+$/g,"")}var d=a("fs"),e=a("lodash.isarray"),f=function(){this.comments=[],this.headers={},this.items=[]};f.prototype.save=function(a,b){d.writeFile(a,this.toString(),b)},f.prototype.toString=function(){var a=[],b=this;this.comments&&this.comments.forEach(function(b){a.push("# "+b)}),a.push('msgid ""'),a.push('msgstr ""');var c=Object.keys(this.headers);return c.forEach(function(c){a.push('"'+c+": "+b.headers[c]+'\\n"')}),a.push(""),this.items.forEach(function(b){a.push(b.toString()),a.push("")}),a.join("\n")},f.load=function(a,b){d.readFile(a,"utf-8",function(a,c){if(a)return b(a);var d=f.parse(c);b(null,d)})},f.parse=function(a){function b(){j.msgid.length>0&&(e.items.push(j),j=new f.Item)}function d(a){return a=c(a),a=a.replace(/^[^"]*"|"$/g,""),a=a.replace(/\\"/g,'"'),a=a.replace(/\\\\/g,"\\")}a=a.replace(/\r\n/g,"\n");var e=new f,g=a.split(/\n\n/),h=g.shift(),i=g.join("\n").split(/\n/);e.headers={"Project-Id-Version":"","Report-Msgid-Bugs-To":"","POT-Creation-Date":"","PO-Revision-Date":"","Last-Translator":"",Language:"","Language-Team":"","Content-Type":"","Content-Transfer-Encoding":"","Plural-Forms":""},h.split(/\n/).forEach(function(a){if(a.match(/^#/)&&e.comments.push(a.replace(/^#\s*/,"")),a.match(/^"/)){a=a.trim().replace(/^"/,"").replace(/\\n"$/,"");var b=a.split(/:/),c=b.shift().trim(),d=b.join(":").trim();e.headers[c]=d}});for(var j=new f.Item,k=null,l=0;i.length>0;){var m=c(i.shift());if(m.match(/^#:/))b(),j.references.push(c(m.replace(/^#:/,"")));else if(m.match(/^#,/)){b();for(var n=c(m.replace(/^#,/,"")).split(","),o=0;o<n.length;o++)j.flags[n[o]]=!0}else if(m.match(/^#/))b(),j.comments.push(c(m.replace(/^#/,"")));else if(m.match(/^msgid_plural/))j.msgid_plural=d(m),k="msgid_plural";else if(m.match(/^msgid/))b(),j.msgid=d(m),k="msgid";else if(m.match(/^msgstr/)){var p=m.match(/^msgstr\[(\d+)\]/);l=p&&p[1]?parseInt(p[1]):0,j.msgstr[l]=d(m),k="msgstr"}else m.length>0&&("msgstr"===k?j.msgstr[l]+=d(m):"msgid"===k?j.msgid+=d(m):"msgid_plural"===k&&(j.msgid_plural+=d(m)))}return b(),e},f.Item=function(){this.msgid="",this.references=[],this.msgid_plural=null,this.msgstr=[],this.comments=[],this.flags={}},f.Item.prototype.toString=function(){var a=[],b=this,c=function(a,b,c){var d=[],e=b.split(/\n/),f="undefined"!=typeof c?"["+c+"]":"";return e.length>1?(d.push(a+f+' ""'),e.forEach(function(a){d.push('"'+a+'"')})):d.push(a+f+' "'+b+'"'),d};this.references.length>0&&this.references.forEach(function(b){a.push("#: "+b)});var d=Object.keys(this.flags);return d.length>0&&a.push("#, "+d.join(",")),["msgid","msgid_plural","msgstr"].forEach(function(d){var f=b[d];null!=f&&(e(f)&&f.length>1?f.forEach(function(b,e){a=a.concat(c(d,b,e))}):(f=e(f)?f.join():f,a=a.concat(c(d,f))))}),a.join("\n")},b.exports=f},{fs:3,"lodash.isarray":4}],pofile:[function(a,b){b.exports=a("GPUdqu")},{}],3:[function(){},{}],4:[function(a,b){var c=a("lodash._isnative"),d="[object Array]",e=Object.prototype,f=e.toString,g=c(g=Array.isArray)&&g,h=g||function(a){return a&&"object"==typeof a&&"number"==typeof a.length&&f.call(a)==d||!1};b.exports=h},{"lodash._isnative":5}],5:[function(a,b){function c(a){return"function"==typeof a&&f.test(a)}var d=Object.prototype,e=d.toString,f=RegExp("^"+String(e).replace(/[.*+?^${}()|[\]\\]/g,"\\$&").replace(/toString| for [^\]]+/g,".*?")+"$");b.exports=c},{}]},{},["GPUdqu"]);
+require=function a(b,c,d){function e(g,h){if(!c[g]){if(!b[g]){var i="function"==typeof require&&require;if(!h&&i)return i(g,!0);if(f)return f(g,!0);throw new Error("Cannot find module '"+g+"'")}var j=c[g]={exports:{}};b[g][0].call(j.exports,function(a){var c=b[g][1][a];return e(c?c:a)},j,j.exports,a,b,c,d)}return c[g].exports}for(var f="function"==typeof require&&require,g=0;g<d.length;g++)e(d[g]);return e}({W8CkM0:[function(a,b){function c(a){return a.replace(/^\s+|\s+$/g,"")}var d=a("fs"),e=a("lodash.isarray"),f=function(){this.comments=[],this.headers={},this.items=[]};f.prototype.save=function(a,b){d.writeFile(a,this.toString(),b)},f.prototype.toString=function(){var a=[],b=this;this.comments&&this.comments.forEach(function(b){a.push("# "+b)}),a.push('msgid ""'),a.push('msgstr ""');var c=Object.keys(this.headers);return c.forEach(function(c){a.push('"'+c+": "+b.headers[c]+'\\n"')}),a.push(""),this.items.forEach(function(b){a.push(b.toString()),a.push("")}),a.join("\n")},f.load=function(a,b){d.readFile(a,"utf-8",function(a,c){if(a)return b(a);var d=f.parse(c);b(null,d)})},f.parse=function(a){function b(){j.msgid.length>0&&(e.items.push(j),j=new f.Item,j.obsolete=m,m=!1)}function d(a){return a=c(a),a=a.replace(/^[^"]*"|"$/g,""),a=a.replace(/\\"/g,'"'),a=a.replace(/\\\\/g,"\\")}a=a.replace(/\r\n/g,"\n");var e=new f,g=a.split(/\n\n/),h=g.shift(),i=g.join("\n").split(/\n/);e.headers={"Project-Id-Version":"","Report-Msgid-Bugs-To":"","POT-Creation-Date":"","PO-Revision-Date":"","Last-Translator":"",Language:"","Language-Team":"","Content-Type":"","Content-Transfer-Encoding":"","Plural-Forms":""},h.split(/\n/).forEach(function(a){if(a.match(/^#/)&&e.comments.push(a.replace(/^#\s*/,"")),a.match(/^"/)){a=a.trim().replace(/^"/,"").replace(/\\n"$/,"");var b=a.split(/:/),c=b.shift().trim(),d=b.join(":").trim();e.headers[c]=d}});for(var j=new f.Item,k=null,l=0,m=!1;i.length>0;){var n=c(i.shift());if(n.match(/^#\~/)?(m=!0,n=c(n.substring(2))):m=!1,n.match(/^#:/))b(),j.references.push(c(n.replace(/^#:/,"")));else if(n.match(/^#,/)){b();for(var o=c(n.replace(/^#,/,"")).split(","),p=0;p<o.length;p++)j.flags[o[p]]=!0}else if(n.match(/^#\s+/))b(),j.comments.push(c(n.replace(/^#\s+/,"")));else if(n.match(/^#\./))b(),j.extractedComments.push(c(n.replace(/^#\./,"")));else if(n.match(/^msgid_plural/))j.msgid_plural=d(n),k="msgid_plural";else if(n.match(/^msgid/))b(),j.msgid=d(n),k="msgid";else if(n.match(/^msgstr/)){var q=n.match(/^msgstr\[(\d+)\]/);l=q&&q[1]?parseInt(q[1]):0,j.msgstr[l]=d(n),k="msgstr"}else n.match(/^msgctxt/)?(b(),j.msgctxt=d(n)):n.length>0&&("msgstr"===k?j.msgstr[l]+=d(n):"msgid"===k?j.msgid+=d(n):"msgid_plural"===k&&(j.msgid_plural+=d(n)))}return b(),e},f.Item=function(){this.msgid="",this.msgctxt=null,this.references=[],this.msgid_plural=null,this.msgstr=[],this.comments=[],this.extractedComments=[],this.flags={},this.obsolete=!1},f.Item.prototype.toString=function(){var a=[],b=this,c=function(a){return a=a.replace(/\\/g,"\\\\"),a.replace(/"/g,'\\"')},d=function(a,b,d){var e=[],f=b.split(/\n/),g="undefined"!=typeof d?"["+d+"]":"";return f.length>1?(e.push(a+g+' ""'),f.forEach(function(a){e.push('"'+c(a)+'"')})):e.push(a+g+' "'+c(b)+'"'),e};this.comments.forEach(function(b){a.push("# "+b)}),this.extractedComments.forEach(function(b){a.push("#. "+b)}),this.references.forEach(function(b){a.push("#: "+b)});var f=Object.keys(this.flags);return f.length>0&&a.push("#, "+f.join(",")),["msgctxt","msgid","msgid_plural","msgstr"].forEach(function(c){var f=b[c];null!=f&&(e(f)&&f.length>1?f.forEach(function(b,e){a=a.concat(d(c,b,e))}):(f=e(f)?f.join():f,a=a.concat(d(c,f))))}),this.obsolete?"#~ "+a.join("\n#~ "):a.join("\n")},b.exports=f},{fs:3,"lodash.isarray":4}],pofile:[function(a,b){b.exports=a("W8CkM0")},{}],3:[function(){},{}],4:[function(a,b){var c=a("lodash._isnative"),d="[object Array]",e=Object.prototype,f=e.toString,g=c(g=Array.isArray)&&g,h=g||function(a){return a&&"object"==typeof a&&"number"==typeof a.length&&f.call(a)==d||!1};b.exports=h},{"lodash._isnative":5}],5:[function(a,b){function c(a){return"function"==typeof a&&f.test(a)}var d=Object.prototype,e=d.toString,f=RegExp("^"+String(e).replace(/[.*+?^${}()|[\]\\]/g,"\\$&").replace(/toString| for [^\]]+/g,".*?")+"$");b.exports=c},{}]},{},["W8CkM0"]);

lib/po.js

@@ -89,12 +89,15 @@ PO.parse = function (data) {
 
     var item = new PO.Item(),
         context = null,
-        plural = 0;
+        plural = 0,
+        obsolete = false;
 
     function finish() {
         if (item.msgid.length > 0) {
             po.items.push(item);
             item = new PO.Item();
+            item.obsolete = obsolete;
+            obsolete = false;
         }
     }
 
@@ -109,6 +112,14 @@ PO.parse = function (data) {
     while (lines.length > 0) {
         var line = trim(lines.shift()),
             add = false;
+
+        if (line.match(/^#\~/)) { // Obsolete item
+            obsolete = true;
+            line = trim(line.substring(2));
+        } else {
+            obsolete = false;
+        }
+
         if (line.match(/^#:/)) { // Reference
             finish();
             item.references.push(trim(line.replace(/^#:/, '')));
@@ -120,9 +131,13 @@ PO.parse = function (data) {
                 item.flags[flags[i]] = true;
             }
         }
-        else if (line.match(/^#/)) { // Comment
+        else if (line.match(/^#\s+/)) { // Translator comment
             finish();
-            item.comments.push(trim(line.replace(/^#/, '')));
+            item.comments.push(trim(line.replace(/^#\s+/, '')));
+        }
+        else if (line.match(/^#\./)) { // Extracted comment
+            finish();
+            item.extractedComments.push(trim(line.replace(/^#\./, '')));
         }
         else if (line.match(/^msgid_plural/)) { // Plural form
             item.msgid_plural = extract(line);
@@ -139,6 +154,10 @@ PO.parse = function (data) {
             item.msgstr[plural] = extract(line);
             context = 'msgstr';
         }
+        else if (line.match(/^msgctxt/)) { // Context
+            finish();
+            item.msgctxt = extract(line);
+        }
         else { // Probably multiline string or blank
             if (line.length > 0) {
                 if (context === 'msgstr') {
@@ -160,17 +179,26 @@ PO.parse = function (data) {
 
 PO.Item = function () {
     this.msgid = '';
+    this.msgctxt = null;
     this.references = [];
     this.msgid_plural = null;
     this.msgstr = [];
-    this.comments = [];
+    this.comments = []; // translator comments
+    this.extractedComments = [];
     this.flags = {};
+    this.obsolete = false;
 };
 
 PO.Item.prototype.toString = function () {
     var lines = [],
         that = this;
 
+    // reverse what extract(string) method during PO.parse does
+    var _escape = function (string) {
+        string = string.replace(/\\/g, '\\\\');
+        return string.replace(/"/g, '\\"');
+    };
+
     var _process = function (keyword, text, i) {
         var lines = [],
             parts = text.split(/\n/),
@@ -178,27 +206,36 @@ PO.Item.prototype.toString = function () {
         if (parts.length > 1) {
             lines.push(keyword + index + ' ""');
             parts.forEach(function (part) {
-                lines.push('"' + part + '"');
+                lines.push('"' + _escape(part) + '"');
             });
         }
         else {
-            lines.push(keyword + index + ' "' + text + '"');
+            lines.push(keyword + index + ' "' + _escape(text) + '"');
         }
         return lines;
     };
 
-    if (this.references.length > 0) {
-        this.references.forEach(function (ref) {
-            lines.push('#: ' + ref);
-        });
-    }
+    // https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
+    // says order is translator-comments, extracted-comments, references, flags
+
+    this.comments.forEach(function (c) {
+        lines.push('# ' + c);
+    });
+
+    this.extractedComments.forEach(function (c) {
+        lines.push('#. ' + c);
+    });
+
+    this.references.forEach(function (ref) {
+        lines.push('#: ' + ref);
+    });
 
     var flags = Object.keys(this.flags);
     if (flags.length > 0) {
         lines.push('#, ' + flags.join(","));
     }
 
-    ['msgid', 'msgid_plural', 'msgstr'].forEach(function (keyword) {
+    ['msgctxt', 'msgid', 'msgid_plural', 'msgstr'].forEach(function (keyword) {
         var text = that[keyword];
         if (text != null) {
             if (isArray(text) && text.length > 1) {
@@ -213,7 +250,11 @@ PO.Item.prototype.toString = function () {
         }
     });
 
-    return lines.join("\n");
+    if (this.obsolete) {
+        return "#~ " + lines.join("\n#~ ");
+    } else {
+        return lines.join("\n");
+    }
 };
 
 module.exports = PO;

package.json

@@ -1,14 +1,18 @@
 {
   "name": "pofile",
   "description": "Parse and serialize Gettext PO files.",
-  "version": "0.2.0",
+  "version": "0.2.7",
   "author": {
     "name": "Ruben Vermeersch",
     "email": "ruben@savanne.be",
     "url": "http://savanne.be/"
   },
   "contributors": [
-    "Mike Holly"
+    "Eyal Lewinsohn",
+    "Gabe Gorelick",
+    "Julian Bäume",
+    "Mike Holly",
+    "Sander Houttekier"
   ],
   "homepage": "http://github.com/rubenv/pofile",
   "repository": {
@@ -24,7 +28,8 @@
     "po"
   ],
   "scripts": {
-    "test": "grunt test"
+    "test": "grunt test",
+    "prepublish": "grunt build"
   },
   "directories": {
     "test": "test"

test/fixtures/big.po

@@ -285,3 +285,13 @@ msgstr "Attribut 'title' du lien"
 # Comment
 msgid "Title, as plain text"
 msgstr "Attribut title, en tant que texte brut"
+
+# Empty should be adjective
+msgctxt "folder display"
+msgid "Empty folder"
+msgstr "This folder is empty."
+
+# Empty should be verb
+msgctxt "folder action"
+msgid "Empty folder"
+msgstr "Make this folder empty."

test/fixtures/c-strings.po

@@ -0,0 +1,19 @@
+# French translation of Link (6.x-2.9)
+# Copyright (c) 2011 by the French translation team
+msgid ""
+msgstr ""
+"Project-Id-Version: Link (6.x-2.9)\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2011-12-31 23:39+0000\n"
+"PO-Revision-Date: 2013-12-17 14:59+0100\n"
+"Last-Translator: Ruben Vermeersch <ruben@rocketeer.be>\n"
+"Language: fr\n"
+"Language-Team: French\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+"MIME-Version: 1.0\n"
+"X-Generator: Poedit 1.6.2\n"
+
+msgid "The name field must not contain characters like \" or \\"
+msgstr ""

test/fixtures/comment.po

@@ -15,6 +15,7 @@ msgstr ""
 "Language: fr\n"
 "X-Generator: Poedit 1.6.2\n"
 
-# Comment
+# Translator comment
+#. Extracted comment
 msgid "Title, as plain text"
 msgstr "Attribut title, en tant que texte brut"

test/fixtures/commented.po

@@ -0,0 +1,23 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: Test\n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: 2014-02-17 14:11+0100\n"
+"Last-Translator: Ruben Vermeersch <ruben@rocketeer.be>\n"
+"Language-Team: \n"
+"Language: nl\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"X-Generator: Poedit 1.6.4\n"
+"X-Poedit-SourceCharset: UTF-8\n"
+"X-POOTLE-MTIME: 1390921449.000000\n"
+
+
+#: .tmp/ui/settings/views/console-modal.html
+msgid "{{dataLoader.data.length}} results"
+msgstr "{{dataLoader.data.length}} resultaten"
+
+#~ msgid "Add order"
+#~ msgstr "Order toevoegen"

test/parse.js

@@ -6,7 +6,7 @@ describe('Parse', function () {
     it('Parses the big po file', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/big.po', 'utf8'));
         assert.notEqual(po, null);
-        assert.equal(po.items.length, 67);
+        assert.equal(po.items.length, 69);
         
         var item = po.items[0];
         assert.equal(item.msgid, "Title");
@@ -23,7 +23,7 @@ describe('Parse', function () {
         assert.equal(item.msgstr, "Les ébauches de jetons suivantes peuvent être utilisées à la fois dans les chemins et dans les titres. Lorsqu'elles sont utilisées dans un chemin ou un titre, elles seront remplacées par les valeurs appropriées.");
     });
 
-    it('Handles string comments', function () {
+    it('Handles translator comments', function () {
         var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8'));
         assert.notEqual(po, null);
         assert.equal(po.items.length, 1);
@@ -31,7 +31,18 @@ describe('Parse', function () {
         var item = po.items[0];
         assert.equal(item.msgid, "Title, as plain text");
         assert.equal(item.msgstr, "Attribut title, en tant que texte brut");
-        assert.deepEqual(item.comments, ["Comment"]);
+        assert.deepEqual(item.comments, ["Translator comment"]);
+    });
+
+    it('Handles extracted comments', function () {
+        var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8'));
+        assert.notEqual(po, null);
+        assert.equal(po.items.length, 1);
+
+        var item = po.items[0];
+        assert.equal(item.msgid, "Title, as plain text");
+        assert.equal(item.msgstr, "Attribut title, en tant que texte brut");
+        assert.deepEqual(item.extractedComments, ["Extracted comment"]);
     });
 
     it('Handles string references', function () {
@@ -62,4 +73,47 @@ describe('Parse', function () {
         assert.notEqual(item.flags, null);
         assert.equal(item.flags.fuzzy, true);
     });
+
+    it('Parses item context', function () {
+        var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/big.po', 'utf8'));
+
+        var ambiguousItems = po.items.filter(function (item) {
+            return item.msgid === 'Empty folder';
+        });
+
+        assert.equal(ambiguousItems[0].msgctxt, 'folder display');
+        assert.equal(ambiguousItems[1].msgctxt, 'folder action');
+    });
+
+    it('Handles obsolete items', function () {
+        var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/commented.po', 'utf8'));
+
+        assert.equal(po.items.length, 2);
+        var item = po.items[0];
+        assert.equal(item.obsolete, false);
+        assert.equal(item.msgid, "{{dataLoader.data.length}} results");
+        assert.equal(item.msgstr, "{{dataLoader.data.length}} resultaten");
+
+        item = po.items[1];
+        assert.equal(item.obsolete, true);
+        assert.equal(item.msgid, "Add order");
+        assert.equal(item.msgstr, "Order toevoegen");
+    });
+
+    describe('C-Strings', function () {
+        it('should parse the c-strings.po file', function () {
+            var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8'));
+
+            assert.notEqual(po, null);
+        });
+
+        it('should extract strings containing " and \\ characters', function () {
+            var po = PO.parse(fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8'));
+
+            var items = po.items.filter(function (item) {
+                return (/^The name field must not contain/).test(item.msgid);
+            });
+            assert.equal(items[0].msgid, 'The name field must not contain characters like " or \\');
+        });
+    });
 });

test/write.js

@@ -37,4 +37,76 @@ describe('Write', function () {
         var str = po.toString();
         assertHasLine(str, "msgstr \"Source\"");
     });
+
+    it('write translator comment', function () {
+        var input = fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8');
+        var po = PO.parse(input);
+        var str = po.toString();
+        assertHasLine(str, "# Translator comment");
+    });
+
+    it('write extracted comment', function () {
+        var input = fs.readFileSync(__dirname + '/fixtures/comment.po', 'utf8');
+        var po = PO.parse(input);
+        var str = po.toString();
+        assertHasLine(str, '#. Extracted comment');
+    });
+
+    it('write obsolete items', function () {
+        var input = fs.readFileSync(__dirname + '/fixtures/commented.po', 'utf8');
+        var po = PO.parse(input);
+        var str = po.toString();
+
+        assertHasLine(str, '#~ msgid "Add order"');
+        assertHasLine(str, '#~ msgstr "Order toevoegen"');
+    });
+
+    describe('C-Strings', function () {
+        it('should escape "', function () {
+            var item = new PO.Item();
+
+            item.msgid = '" should be written escaped';
+            assertHasLine(item.toString(), 'msgid "\\" should be written escaped"');
+        });
+
+        it('shoudl escape \\', function () {
+            var item = new PO.Item();
+
+            item.msgid = '\\ should be written escaped';
+            assertHasLine(item.toString(), 'msgid "\\\\ should be written escaped"');
+        });
+
+        it('should write identical file after parsing a file', function () {
+            var input = fs.readFileSync(__dirname + '/fixtures/c-strings.po', 'utf8');
+            var po = PO.parse(input);
+            var str = po.toString();
+
+            assert.equal(str, input);
+        });
+    });
+
+    describe('msgctxt', function () {
+        it('should write context field to file', function () {
+            var input = fs.readFileSync(__dirname + '/fixtures/big.po', 'utf8');
+            var po = PO.parse(input);
+            var str = po.toString();
+            assertHasLine(str, 'msgctxt "folder action"');
+        });
+
+        it('should ignore omitted context field', function () {
+            var po = new PO();
+            var item = new PO.Item();
+            po.items.push(item);
+            assert.ok(po.toString().indexOf('msgctxt') < 0);
+        });
+
+        it('should write empty context field', function () {
+            var po = new PO();
+            var item = new PO.Item();
+
+            item.msgctxt = '';
+            po.items.push(item);
+            assert.ok(po.toString().indexOf('msgctxt') >= 0);
+        });
+    });
 });