Improve documentation about translations in API (bug 946738)

https://bugzilla.mozilla.org/show_bug.cgi?id=946738