Added localization language support

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
 *.egg-info
 *.egg
+*.mo
 *build/
 .tox
 .coverage
@@ -9,10 +10,15 @@
 *.map
 .ropeproject/
 .ruby-version
+bin/
 dist/
 bower_components/
+include/
+lib/
+local/
 node_modules
 npm-debug.log
 package-lock.json
+pip-selfcheck.json
 sphinx_rtd_theme/static/fonts/Lato/
 sphinx_rtd_theme/static/fonts/RobotoSlab/

.travis.yml

@@ -10,6 +10,7 @@ matrix:
       env: TOXENV=docs
 install:
   - pip install tox-travis
+  - pip install sphinx
 script:
   - tox
 

MANIFEST.in

@@ -1,4 +1,5 @@
 include *.txt
+include babel.cfg
 include LICENSE
 recursive-include sphinx_rtd_theme *.conf
 recursive-include sphinx_rtd_theme *.css
@@ -9,5 +10,7 @@ recursive-include sphinx_rtd_theme *.svg
 recursive-include sphinx_rtd_theme *.ttf
 recursive-include sphinx_rtd_theme *.woff
 recursive-include sphinx_rtd_theme *.woff2
+recursive-include sphinx_rtd_theme/locale *.pot *.po *.mo
 recursive-include tests *.py
 recursive-include tests *.rst
+prune build

README.rst

@@ -5,7 +5,7 @@ Read the Docs Sphinx Theme
 
 .. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
    :target: https://pypi.python.org/pypi/sphinx_rtd_theme
-   :alt: Pypi Version 
+   :alt: Pypi Version
 .. image:: https://travis-ci.org/rtfd/sphinx_rtd_theme.svg?branch=master
    :target: https://travis-ci.org/rtfd/sphinx_rtd_theme
    :alt: Build Status
@@ -52,3 +52,9 @@ Contributing
 If you would like to help improve the theme or have more control
 over the theme in case of a fork please read our contributing guide
 `here <https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html>`__.
+
+Translations
+------------
+
+You can help to translate the Read the Docs Sphinx Theme,
+please read the :doc:`translations </docs/translations>` guide for more details.

babel.cfg

@@ -0,0 +1,10 @@
+# How setup this file
+# http://babel.pocoo.org/en/latest/setup.html
+# this file description:
+# http://babel.pocoo.org/en/latest/messages.html#extraction-method-mapping-and-configuration
+
+# Extraction from Jinja2 HTML templates
+[jinja2: **/**.html]
+encoding = utf-8
+ignore_tags = script,style
+include_attrs = alt title summary placeholder

docs/changelog.rst

@@ -2,12 +2,16 @@
 Changelog
 *********
 
-master
+Master
 ======
 
 New Features
 -------------
 
+* Added Spanish translation
+* Added i18n support using Babel
+* Added Translation Guide documentation
+
 Fixes
 -----
 
@@ -91,7 +95,7 @@ Fixes
 * Color accessibility improvements on the left navigation
 
 Other Changes
---------------
+---------------
 
 * Write theme version and build date at top of JavaScript and CSS
 * Changed code and literals to use a native font stack (#612)

docs/conf.py

@@ -26,6 +26,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',
+    'sphinx_rtd_theme',
 ]
 
 templates_path = ['_templates']

docs/index.rst

@@ -8,6 +8,7 @@
    configuring
    changelog
    contributing
+   translations
 
 
 .. toctree::

docs/translations.rst

@@ -0,0 +1,192 @@
+
+******************
+Translation Guide
+******************
+
+.. contents::
+
+You can help to translate the Read the Docs Sphinx Theme.
+
+Installation
+============
+
+For translating the Read the Docs Sphinx Theme you will need to install the following packages:
+
+.. code:: bash
+
+    $ pip install babel Jinja2
+
+Translating Applications with Babel
+-----------------------------------
+
+After you marked all the strings you want to translate in this Sphinx theme with the gettext function 
+alias ``_('str')`` or ``{% trans %}string 1, string 2, string 3, etc.{% endtrans %}`` blocks.
+
+Then it’s time to create a .pot file. A .pot file contains all the strings and is the template for a 
+.po file which contains the translated strings. The ``babel`` package can do all that for you.
+
+Configuration
+=============
+
+For enable the *Internationalization and Localization* for this Sphinx Theme, you will need checkout 
+the following configurations:
+
+Translations files
+------------------
+
+The translations files are based on ``gettext`` format and they are placed at the 
+:file:`sphinx_rtd_theme/locale/` directory, like it showing the following structure:
+
+.. code:: bash
+
+    sphinx_rtd_theme/locale/
+    ├── es
+    │   └── LC_MESSAGES
+    │       ├── sphinx.mo
+    │       └── sphinx.po
+    └── sphinx.pot
+
+:file:`sphinx_rtd_theme/locale/<LANG>/LC_MESSAGES/`
+    This folder contains a specific language is the **Gettext format**.
+
+:file:`sphinx.pot`
+    This file is the **Portable Object Template** Gettext format.
+
+:file:`sphinx.po`
+    This file is the **Portable Object** Gettext format to translate.
+
+Babel Configurations
+--------------------
+
+The ``babel`` packages provides commands for integration into :file:`setup.py` scripts, based on either 
+the ``distutils`` package that is part of the Python standard library, or the third-party ``setuptools`` 
+package.
+
+Then :file:`setup.cfg` file simply configures the behavior of the various setup commands for this package. 
+This file contains the options that you can be specified on the command-line. The :file:`setup.cfg` file 
+at root folder of this Sphinx theme, look like the following:
+
+.. code:: cfg
+
+    [bdist_wheel]
+    universal = 1
+
+    # Babel configurations for setup.py scripts
+    [compile_catalog]
+    domain = sphinx
+    directory = sphinx_rtd_theme/locale/
+
+    [extract_messages]
+    mapping_file = babel.cfg
+    output_file = sphinx_rtd_theme/locale/sphinx.pot
+    keywords = _ l_ lazy_gettext
+
+    [init_catalog]
+    input_file = sphinx_rtd_theme/locale/sphinx.pot
+    output_file = sphinx_rtd_theme/locale/$LANG/LC_MESSAGES/sphinx.po
+
+    [update_catalog]
+    domain = sphinx
+    input_file = sphinx_rtd_theme/locale/sphinx.pot
+    output_dir = sphinx_rtd_theme/locale/
+
+If the command has been correctly installed or registered, a project's setup.py script should 
+allow you to use the following command:
+
+.. code:: bash
+
+    $ python ./setup.py subcommand options
+
+Execute the follow command for more options and follow these instructions to get details:
+
+.. code:: bash
+
+    $ python ./setup.py --help-commands
+
+Extraction Configurations
+-------------------------
+
+First of all you have to get into the folder where you have your Sphinx theme and create a mapping file 
+called :file:`babel.cfg` that contains the **extraction from Jinja2 HTML templates** configurations. 
+For typical Sphinx extensions, this is what you want in there:
+
+.. code:: cfg
+
+    # Extraction from Jinja2 HTML templates
+    [jinja2: **/**.html]
+    encoding = utf-8
+    ignore_tags = script,style
+    include_attrs = alt title summary placeholder
+
+
+.. seealso::
+
+    More details check out the following links:
+
+    - `How setup this file <http://babel.pocoo.org/en/latest/setup.html>`_
+    - `A previous file example description <http://babel.pocoo.org/en/latest/messages.html#extraction-method-mapping-and-configuration>`_
+
+Administrative Tasks
+====================
+
+The ``babel`` package have a *Distutils/Setuptools Integration* which supports the options 
+defined in the :file:`setup.cfg` file that can be executed via command line.
+
+These options are the commonly using as **"Translations Administrative Tasks"** and the most 
+used tasks are described below:
+
+Extract messages
+----------------
+
+It can extract localizable messages from a variety of difference source files, 
+and generate a PO (portable object) template file from the collected messages.
+
+Running the following command will produce a PO template file:
+
+.. code:: bash
+
+    $ python ./setup.py extract_messages -o ./sphinx_rtd_theme/locale/sphinx.pot
+
+.. tip::
+
+    More options please, check out http://babel.pocoo.org/en/latest/setup.html#extract-messages
+
+Init catalog
+------------
+
+It creates a new translation catalog based on a PO template file (POT). Running the following 
+command will produce a PO file:
+
+.. code:: bash
+
+    $ python ./setup.py init_catalog -l es -i ./sphinx_rtd_theme/locale/sphinx.pot \
+                                     -o ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po
+
+.. tip::
+
+    More options please, check out http://babel.pocoo.org/en/latest/setup.html#init-catalog
+
+Update catalog
+--------------
+
+It updates an existing translations catalog based on a PO template file (POT). Running the following 
+command will update a PO file:
+
+.. code:: bash
+
+    $ python ./setup.py update_catalog -l es -i ./sphinx_rtd_theme/locale/sphinx.pot \
+                                             -o ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po
+
+.. tip::
+
+    More options please, check out http://babel.pocoo.org/en/latest/setup.html#update-catalog
+
+Compile catalog
+---------------
+
+It compile catalog an existing translations based on PO files into MO files. Running the following 
+command will compile catalog of PO files:
+
+.. code:: bash
+
+    $ python ./setup.py compile_catalog -d ./sphinx_rtd_theme/locale/

setup.cfg

@@ -1,2 +1,22 @@
 [bdist_wheel]
 universal = 1
+
+# Babel configurations for setup.py scripts
+# http://babel.pocoo.org/en/latest/setup.html
+[extract_messages]
+mapping_file = babel.cfg
+output_file = sphinx_rtd_theme/locale/sphinx.pot
+keywords = _ l_ lazy_gettext
+
+[init_catalog]
+input_file = sphinx_rtd_theme/locale/sphinx.pot
+output_file = sphinx_rtd_theme/locale/$LANG/LC_MESSAGES/sphinx.po
+
+[update_catalog]
+domain = sphinx
+input_file = sphinx_rtd_theme/locale/sphinx.pot
+output_dir = sphinx_rtd_theme/locale/
+
+[compile_catalog]
+domain = sphinx
+directory = sphinx_rtd_theme/locale/

sphinx_rtd_theme/__init__.py

@@ -4,6 +4,7 @@
 
 """
 from os import path
+import sphinx
 
 
 __version__ = '0.4.3.dev0'
@@ -19,3 +20,11 @@ def get_html_theme_path():
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
+
+    # for sphinx-1.8 or later
+    if sphinx.version_info[0:3] >= (1,8,0):
+
+        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
+
+        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
+        app.add_message_catalog('sphinx', rtd_locale_path)

sphinx_rtd_theme/breadcrumbs.html

@@ -71,10 +71,10 @@
   {% if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
   <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="breadcrumb navigation">
       {% if next %}
-        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">{{ _('Next') }} <span class="fa fa-arrow-circle-right"></span></a>
       {% endif %}
       {% if prev %}
-        <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> {{ _('Previous') }}</a>
       {% endif %}
   </div>
   {% endif %}