Merge pull request #557 from edx/sarina/i18n-update

Update i18n documentation about Mako and Underscore templates.

en_us/developers/source/internationalization/i18n.rst

@@ -73,7 +73,7 @@ The code samples below show how to do each of these things for:
 * `JavaScript files`_
 * `Coffeescript files`_
 * `Underscore template files`_
-* `Other kinds of code`_
+* `Other types of content`_
 
 Note that you have to take into account not just the programming language involved,
 but the type of file: JavaScript embedded in an HTML Mako template is treated differently
@@ -137,9 +137,14 @@ functions first. Here's a Mako template example::
 
     <%! from django.utils.translation import ugettext as _ %>
  
-    ## Translators: message to the translator
+    ## Translators: message to the translator. This comment may
+    ## wrap on to multiple lines if needed, as long as they are
+    ## lines directly above the marked up string.
     ${_("Welcome!")}
 
+Make sure that all Mako comments, including translators comments, begin
+with *two* pound signs (#).
+
 JavaScript files
 ================
 
@@ -221,8 +226,15 @@ Note: it is recommended that you use ``<%-`` for all translated strings
 as this will HTML escape the string before including it in the page. This
 ensures that translations are free to use non-HTML characters.
 
-Other kinds of code
-===================
+Currently, translators comments are not supported in Underscore template files,
+as the underlying library does not parse them out. We recommend you add them in
+using standard comment syntax, so that when work is done to support these comments,
+we already have them defined. Additionally, translators comments in the code
+will enable us to answer questions from translators.
+
+
+Other types of content
+======================
 
 We have not yet established guidelines for internationalizing the following.