From 37235c71e04aff3b93ae98f12456a34666635a9d Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Fri, 14 Aug 2020 16:11:23 +0900
Subject: [PATCH] Fix #6640: i18n: Failed to override system message
 translation

Our document describes that users can override system messages via
their own message catalog named `sphinx.mo` under the locale_dirs.
But it has not been used since its beginning of i18n mechanism because
the priority of users' message catalog is lower than system's.

This makes the priority of users' message catalog higher than system's.
---
 CHANGES                   |  1 +
 sphinx/application.py     |  7 +++++--
 sphinx/locale/__init__.py |  2 +-
 tests/test_intl.py        | 29 +++++++++++++++++++++++++++++
 4 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index e30d42e43a8..481ade0b855 100644
--- a/CHANGES
+++ b/CHANGES
@@ -27,6 +27,7 @@ Bugs fixed
 ----------
 
 * #8085: i18n: Add support for having single text domain
+* #6640: i18n: Failed to override system message translation
 * #8143: autodoc: AttributeError is raised when False value is passed to
   autodoc_default_options
 * #8103: autodoc: functools.cached_property is not considered as a property
diff --git a/sphinx/application.py b/sphinx/application.py
index 385b74d8a1c..f91027bf79b 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -18,7 +18,7 @@
 from collections import deque
 from io import StringIO
 from os import path
-from typing import Any, Callable, Dict, IO, List, Tuple, Union
+from typing import Any, Callable, Dict, IO, List, Optional, Tuple, Union
 
 from docutils import nodes
 from docutils.nodes import Element, TextElement
@@ -293,7 +293,10 @@ def _init_i18n(self) -> None:
                 if catalog.domain == 'sphinx' and catalog.is_outdated():
                     catalog.write_mo(self.config.language)
 
-            locale_dirs = [None, path.join(package_dir, 'locale')] + list(repo.locale_dirs)
+            locale_dirs = [None]  # type: List[Optional[str]]
+            locale_dirs += list(repo.locale_dirs)
+            locale_dirs += [path.join(package_dir, 'locale')]
+
             self.translator, has_translation = locale.init(locale_dirs, self.config.language)
             if has_translation or self.config.language == 'en':
                 # "en" never needs to be translated
diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py
index 385ca356605..5210dc7252e 100644
--- a/sphinx/locale/__init__.py
+++ b/sphinx/locale/__init__.py
@@ -106,7 +106,7 @@ def __repr__(self) -> str:
 translators = defaultdict(NullTranslations)  # type: Dict[Tuple[str, str], NullTranslations]
 
 
-def init(locale_dirs: List[str], language: str,
+def init(locale_dirs: List[Optional[str]], language: str,
          catalog: str = 'sphinx', namespace: str = 'general') -> Tuple[NullTranslations, bool]:
     """Look for message catalogs in `locale_dirs` and *ensure* that there is at
     least a NullTranslations catalog set in `translators`. If called multiple
diff --git a/tests/test_intl.py b/tests/test_intl.py
index 1d1282baa35..c0b87d5ceb6 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -14,8 +14,10 @@
 
 import pytest
 from babel.messages import pofile, mofile
+from babel.messages.catalog import Catalog
 from docutils import nodes
 
+from sphinx import locale
 from sphinx.testing.util import (
     path, etree_parse, strip_escseq,
     assert_re_search, assert_not_re_search, assert_startswith, assert_node
@@ -1289,3 +1291,30 @@ def test_image_glob_intl_using_figure_language_filename(app):
 
 def getwarning(warnings):
     return strip_escseq(warnings.getvalue().replace(os.sep, '/'))
+
+
+@pytest.mark.sphinx('html', testroot='basic', confoverrides={'language': 'de'})
+def test_customize_system_message(make_app, app_params, sphinx_test_tempdir):
+    try:
+        # clear translators cache
+        locale.translators.clear()
+
+        # prepare message catalog (.po)
+        locale_dir = sphinx_test_tempdir / 'basic' / 'locales' / 'de' / 'LC_MESSAGES'
+        locale_dir.makedirs()
+        with (locale_dir / 'sphinx.po').open('wb') as f:
+            catalog = Catalog()
+            catalog.add('Quick search', 'QUICK SEARCH')
+            pofile.write_po(f, catalog)
+
+        # construct application and convert po file to .mo
+        args, kwargs = app_params
+        app = make_app(*args, **kwargs)
+        assert (locale_dir / 'sphinx.mo').exists()
+        assert app.translator.gettext('Quick search') == 'QUICK SEARCH'
+
+        app.build()
+        content = (app.outdir / 'index.html').read_text()
+        assert 'QUICK SEARCH' in content
+    finally:
+        locale.translators.clear()