docs: Add comment links to i18n documentation.

static/js/i18n.js

@@ -1,3 +1,6 @@
+// For documentation on i18n in Zulip, see:
+// https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+
 import i18next from "i18next";
 
 i18next.init({

tools/i18n/push-translations

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# See https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+# for background on this subsystem.
+
 set -e
 set -x
 

tools/i18n/sync-translations

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# See https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+# for background on this subsystem.
+
 set -e
 set -x
 

zerver/lib/i18n.py

@@ -1,3 +1,5 @@
+# See https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+
 import logging
 import operator
 import os

zerver/lib/send_email.py

@@ -99,6 +99,16 @@ def build_email(template_prefix: str, to_user_ids: Optional[List[int]]=None,
             html_message = loader.render_to_string(compiled_template_prefix + '.html', context)
         return (html_message, message, email_subject)
 
+    # The i18n story for emails is a bit complicated.  For emails
+    # going to a single user, we want to use the language that user
+    # has configured for their Zulip account.  For emails going to
+    # multiple users or to email addresses without a known Zulip
+    # account (E.g. invitations), we want to use the default language
+    # configured for the Zulip organization.
+    #
+    # See our i18n documentation for some high-level details:
+    # https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+
     if not language and to_user_ids is not None:
         language = to_users[0].default_language
     if language:

zerver/management/commands/makemessages.py

@@ -1,4 +1,7 @@
 """
+See https://zulip.readthedocs.io/en/latest/translating/internationalization.html
+for background.
+
 The contents of this file are taken from
 https://github.com/niwinz/django-jinja/blob/master/django_jinja/management/commands/makemessages.py