From 3286fbe8e37ec81c2a2005ee6f478bb1c5568019 Mon Sep 17 00:00:00 2001
From: Greg Price <gnprice@gmail.com>
Date: Wed, 21 Jun 2017 16:29:23 -0700
Subject: [PATCH] docs/translating: Follow-on cleanups from removing Django
 templates.

This follows up the recent commit
3d1d09b3d docs: Remove discussion of old Django templating engine.
with a small grammar fix and removing another vestige of making the
distinction between Jinja2 and Django templates, and also rearranges
the logic slightly to reflect that backend and frontend templates
have separate sections.

Probably a bigger restructuring is in order to help the reader
navigate through all the good content in this doc, but that's
a bigger job for another day.
---
 docs/translating.md | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/docs/translating.md b/docs/translating.md
index bc9ab63c3f..11f7921f5a 100644
--- a/docs/translating.md
+++ b/docs/translating.md
@@ -208,23 +208,18 @@ These files are uploaded to [Transifex][], where they can be translated.
 ## Backend translations
 
 All user-facing text in the Zulip UI should be generated by an HTML
-template so that it can be translated.
+template so that it can be translated.  For text generated in the
+backend, including logged-out ("portico") pages and the webapp's base
+content, we use the [Jinja2][] template engine.
 
-Zulip's HTML is primarily implemented using two types of HTML
-templates: backend templates (powered by the [Jinja2][] template
-engine used for logged-out ("portico") pages and the webapp's base
-content) and frontend templates (powered by [Handlebars][]) used for
-live-rendering HTML from JavaScript for things like the main message
-feed.
-
-To mark a string for translation in the Jinja2 template engines, you
+To mark a string for translation in a Jinja2 template, you
 can use the `_()` function in the templates like this:
 
 ```
 {{ _("English text") }}
 ```
 
-If a string contains both a literal string component and variables,
+If a piece of text contains both a literal string component and variables,
 you can use a block translation, which makes use of placeholders to
 help translators to translate an entire sentence.  To translate a
 block, Jinja2 uses the [trans][] tag.  So rather than writing
@@ -238,7 +233,6 @@ something ugly and confusing for translators like this:
 You can instead use:
 
 ```
-# Jinja2 style
 {% trans %}This string will have {{ value }} inside.{% endtrans %}
 ```
 
@@ -257,11 +251,14 @@ Zulip linter (`tools/lint`) checks for correct usage.
 
 ## Frontend translations
 
-Zulip uses the [i18next][] library for frontend translations. There
-are two types of files in Zulip frontend which can hold translatable
-strings: JavaScript code files and Handlebar templates. To mark a
-string translatable in JavaScript files, pass it to the `i18n.t`
-function.
+For text generated in the frontend, live-rendering HTML from
+JavaScript for things like the main message feed, we use the
+[Handlebars][] template engine and sometimes work directly from
+JavaScript code.  In both cases, we use the [i18next][] library
+for translations.
+
+To mark a string translatable in JavaScript files, pass it to the
+`i18n.t` function.
 
 ```
 i18n.t('English Text', context);