Fix #3028: figure_language_filename format tokens, document tokens.

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

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)
 

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)