From 59ba8c1dee4451673ca2a96c2946a698ef6a19b4 Mon Sep 17 00:00:00 2001
From: Jonathan Harker <jonathan@catalyst.net.nz>
Date: Thu, 13 Oct 2016 16:34:19 +1300
Subject: [PATCH] Fix #3028: figure_language_filename format tokens, document
 tokens.

---
 doc/config.rst          | 16 ++++++++++++++++
 sphinx/util/i18n.py     | 12 +++++++++---
 tests/test_util_i18n.py | 12 ++++++++++++
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/doc/config.rst b/doc/config.rst
index 8ef6a6de3..fae378a1d 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -599,9 +599,25 @@ documentation on :ref:`intl` for details.
    The filename format for language-specific figures.  The default value is
    ``{root}.{language}{ext}``.  It will be expanded to
    ``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``.
+   The available format tokens are:
+
+   * ``{root}`` - the filename, including any path component, without the file
+     extension, e.g. ``dirname/filename``
+   * ``{path}`` - the directory path component of the filename, with a trailing
+     slash if non-empty, e.g. ``dirname/``
+   * ``{basename}`` - the filename without the directory path or file extension
+     components, e.g. ``filename``
+   * ``{ext}`` - the file extension, e.g. ``.png``
+   * ``{language}`` - the translation language, e.g. ``en``
+
+   For example, setting this to ``{path}{language}/{basename}{ext}`` will
+   expand to ``dirname/en/filename.png`` instead.
 
    .. versionadded:: 1.4
 
+   .. versionchanged:: 1.5
+      Added ``{path}`` and ``{basename}`` tokens.
+
 .. _html-options:
 
 Options for HTML output
diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py
index d0cb1f443..446925cdb 100644
--- a/sphinx/util/i18n.py
+++ b/sphinx/util/i18n.py
@@ -229,10 +229,16 @@ def get_image_filename_for_language(filename, env):
         return filename
 
     filename_format = env.config.figure_language_filename
-    root, ext = path.splitext(filename)
+    d = dict()
+    d['root'], d['ext'] = path.splitext(filename)
+    dirname = path.dirname(d['root'])
+    if dirname and not dirname.endswith(path.sep):
+        dirname += path.sep
+    d['path'] = dirname
+    d['basename'] = path.basename(d['root'])
+    d['language'] = env.config.language
     try:
-        return filename_format.format(root=root, ext=ext,
-                                      language=env.config.language)
+        return filename_format.format(**d)
     except KeyError as exc:
         raise SphinxError('Invalid figure_language_filename: %r' % exc)
 
diff --git a/tests/test_util_i18n.py b/tests/test_util_i18n.py
index 3e0cfd5f3..849796a8f 100644
--- a/tests/test_util_i18n.py
+++ b/tests/test_util_i18n.py
@@ -255,6 +255,18 @@ def test_get_filename_for_language():
         '../foo.png', app.env) == 'images/en/../foo.png'
     assert i18n.get_image_filename_for_language('foo', app.env) == 'images/en/foo'
 
+    # new path and basename tokens
+    app.env.config.language = 'en'
+    app.env.config.figure_language_filename = '{path}{language}/{basename}{ext}'
+    assert i18n.get_image_filename_for_language('foo.png', app.env) == 'en/foo.png'
+    assert i18n.get_image_filename_for_language(
+        'foo.bar.png', app.env) == 'en/foo.bar.png'
+    assert i18n.get_image_filename_for_language(
+        'subdir/foo.png', app.env) == 'subdir/en/foo.png'
+    assert i18n.get_image_filename_for_language(
+        '../foo.png', app.env) == '../en/foo.png'
+    assert i18n.get_image_filename_for_language('foo', app.env) == 'en/foo'
+
     # invalid figure_language_filename
     app.env.config.figure_language_filename = '{root}.{invalid}{ext}'
     raises(SphinxError, i18n.get_image_filename_for_language, 'foo.png', app.env)