Add documentation on translation tags.

[substantially modified by tabbott]

docs/translating.md

@@ -17,3 +17,49 @@ maintainers when you ask to join a project, so please send a quick
 email to zulip-core@googlegroups.com when you request to join the
 project or add a language so that we can be sure to accept your
 request to contribute.
+
+## Translation Tags
+
+All user-facing text in the Zulip UI should be generated by a HTML
+template so that it can be translated.
+
+Zulip uses two types of templates: backend templates (powered by the
+[Jinja2][] template engine, though the original [Django][] template
+engine is still supported) and frontend templates (powered by
+[Handlebars][]).  At present, the frontend templates don't support
+translation (though we're working on fixing this!), so the rest of
+this discussion will be about the backend templates.
+
+To mark a string for translation in the Jinja2 and Django template
+engines, you can use the `_()` function in the templates like this:
+
+```
+{{ _("English text") }}
+```
+
+If a string contains both a literal string component and variables,
+you can use a block translation, which makes use of placeholders to
+help translators to translated an entire sentence.  To translate a
+block, Jinja2 uses the [trans][] tag while Django uses the
+[blocktrans][] tag.  So rather than writing something ugly and
+confusing for translators like this:
+
+```
+# Don't do this!
+{{ _("This string will have") }} {{ value }} {{ _("inside") }}
+```
+
+You can instead use:
+
+```
+# Jinja2 style
+{% trans %}This string will have {{ value }} inside.{% endtrans %}
+# Django style
+{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
+```
+
+[Django]: https://docs.djangoproject.com/en/1.9/topics/templates/#the-django-template-language
+[Jinja2]: http://jinja.pocoo.org/
+[Handlebars]: http://handlebarsjs.com/
+[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
+[blocktrans]: https://docs.djangoproject.com/en/1.8/topics/i18n/translation/#std:templatetag-blocktrans