Allow enabling translations by setting translations_list in config

README.md

@@ -27,6 +27,12 @@ This package is available on PyPI using:
 ```bash
 pip install qiskit-sphinx-theme
 ```
+
+Then, set up the theme by updating `conf.py`:
+
+1. Set `html_theme = "qiskit_sphinx_theme"`
+2. Add `"qiskit_sphinx_theme"` to `extensions`
+
 ## Configure Left Sidebar
 
 To keep UX/UI similar across different Qiskit packages we strongly encourage the following structure for you sidebar, which can be set in the toctree of your `index.rst`:
@@ -118,7 +124,33 @@ To configure your documentation to use exapandable sidebar headings like the exa
 
 *Tip: if you want to add all files in a sub-directory to your expandable dropdown section you can use the `:glob:` directive instead of listing out each page (see example above for the How-to Guides, API Reference and Explanations sections). This will list out each page in alphabetical order, so if you want a specific order you will need to list the pages out individually in the `toctree` (see example above for the Tutorials section)*
 
+## Enable translations
+
+First, coordinate with the Translations team at https://github.com/qiskit-community/qiskit-translations to express your interest and to coordinate setting up the infrastructure.
+
+Once the Translations team is ready, then update your `conf.py`:
 
+* Ensure that `qiskit_sphinx_theme` is in the `extensions` setting.
+* Set the option `translations_list` to a list of pairs of the locale code and the language name, e.g. `[..., ("de_DE", "German")]`.
+* Set the option `content_prefix` to your project's URL prefix, like `ecosystem/finance`.
+
+For example:
+
+```python
+extensions = [
+   ...,
+   "qiskit_sphinx_theme",
+]
+
+translations_list = [
+    ('en', 'English'),
+    ('bn_BN', 'Bengali'),
+    ('fr_FR', 'French'),
+    ('de_DE', 'German'),
+]
+
+content_prefix = "ecosystem/finance"
+```
 
 ## Enable Qiskit.org Analytics
 

example_docs/docs/conf.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018.
+# (C) Copyright IBM 2018, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -13,8 +13,7 @@
 import os
 import sys
 
-# This allows autodoc to find the `api_example` folder and
-# for us to register our `docs.language_utils` extension.
+# This allows autodoc to find the `api_example` folder.
 sys.path.insert(0, os.path.abspath(".."))
 
 project = 'Qiskit sphinx theme'
@@ -41,7 +40,7 @@
     'jupyter_sphinx',
     'sphinx_design',
     "nbsphinx",
-    "sphinxcontrib.jquery",
+    "qiskit_sphinx_theme",
 ]
 
 html_last_updated_fmt = '%Y/%m/%d'
@@ -71,6 +70,14 @@
     'expandable_sidebar': True
 }
 
+# When creating a new repo, follow the instructions in this repo's README.md on
+# `Enable translations`. Remove this value if you aren't using translations.
+translations_list = [
+    ('en', 'English'),
+    ('bn_BN', 'Bengali'),
+    ('fr_FR', 'French'),
+]
+
 # This allows RST files to put `|version|` in their file and
 # have it updated with the release set in conf.py.
 rst_prolog = f"""
@@ -96,8 +103,3 @@
 nbsphinx_thumbnails = {
     "sphinx_guide/notebook": "_static/no_image.png",
 }
-
-
-def setup(app):
-    """Entry point for Sphinx extensions."""
-    app.setup_extension('docs.language_utils')

qiskit_sphinx_theme/__init__.py

@@ -3,6 +3,8 @@
 from pathlib import Path
 from warnings import warn
 
+from qiskit_sphinx_theme import translations
+
 __version__ = '1.11.0rc1'
 __version_full__ = __version__
 
@@ -32,15 +34,15 @@ def get_html_theme_path():
 
 # See https://www.sphinx-doc.org/en/master/development/theming.html
 def setup(app):
-    # Sphinx 6 stopped including jQuery by default. Our Pytorch theme depend on jQuery,
-    # so install it for our users automatically.
-    app.setup_extension("sphinxcontrib.jquery")
+    # We always activate translations support, but users need to set `translations_list` in config
+    # for it to be used.
+    translations.setup(app)
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch_base"))
     app.add_html_theme("_qiskit_furo", _get_theme_absolute_path("furo/base"))
 
-    # The below must be kept in sync with `furo/__init__.py`.
     if app.config.html_theme == "_qiskit_furo":
+        # The below must be kept in sync with `furo/__init__.py`.
         from furo import (
             WrapTableAndMathInAContainerTransform,
             _builder_inited,
@@ -52,5 +54,9 @@ def setup(app):
         app.connect("html-page-context", _html_page_context)
         app.connect("builder-inited", _builder_inited)
         app.connect("build-finished", _overwrite_pygments_css)
+    else:
+        # Sphinx 6 stopped including jQuery by default. Our Pytorch theme depend on jQuery,
+        # so activate it for our users automatically.
+        app.setup_extension("sphinxcontrib.jquery")
 
     return {'parallel_read_safe': True, 'parallel_write_safe': True}

example_docs/docs/language_utils.py → qiskit_sphinx_theme/translations.py

@@ -2,7 +2,7 @@
 
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018.
+# (C) Copyright IBM 2018, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -12,50 +12,28 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-# THIS EXTENSION IS BASED ON versionutils.py IN qiskit-metapackage/docs
-
 from functools import partial
 
-from sphinx.util import logging
-
-
-logger = logging.getLogger(__name__)
-
-translations_list = [
-    ('en', 'English'),
-    ('bn_BN', 'Bengali'),
-    ('fr_FR', 'French'),
-    ('de_DE', 'German'),
-    ('ja_JP', 'Japanese'),
-    ('ko_KR', 'Korean'),
-    ('pt_UN', 'Portuguese'),
-    ('es_UN', 'Spanish'),
-    ('ta_IN', 'Tamil'),
-]
-
 default_language = 'en'
 
 
 def setup(app):
     app.connect('config-inited', _extend_html_context)
-    app.add_config_value('content_prefix', '', '')
-    app.add_config_value('translations', True, 'html')
-    return dict(parallel_read_safe=True)
+    app.add_config_value("content_prefix", default="", rebuild="", types=[str])
+    app.add_config_value("translations_list", default=[], rebuild="html", types=[list])
 
 
 def _extend_html_context(app, config):
     context = config.html_context
-    context['translations'] = config.translations
-    context['translations_list'] = translations_list
-    context['current_translation'] = _get_current_translation(config) or config.language
+    context['translations_list'] = config.translations_list
     context['translation_url'] = partial(_get_translation_url, config)
     context['language_label'] = _get_language_label(config)
 
 
 def _get_current_translation(config):
     language = config.language or default_language
     try:
-        found = next(v for k, v in translations_list if k == language)
+        found = next(v for k, v in config.translations_list if k == language)
     except StopIteration:
         found = None
     return found