Error when internationalizing documentation using sphinx and nbsphinx

iamdalio commented 1 year ago

Describe the bug

When attempting to internationalize Sphinx documentation that contains ipynb files using the make -e SPHINXOPTS="-D language='de'" html command, the following error occurs:

  docs/ecosystem/aim_tracking.ipynb:7: ERROR: Unexpected indentation.

How to Reproduce

clone doc files git clone https://github.com/hwchase17/langchain.git
cd langchain/docs
Add configurations to conf.py. locale_dirs = ['locale/'] # path is example but recommended.
make gettext
sphinx-intl update -p _build/gettext -l de

Translate po files. Notice: modify msgstr in ipynb files

#: ../../ecosystem/aim_tracking.ipynb:10002
msgid "Aim"
msgstr "Aim dasd 11"

make -e SPHINXOPTS="-D language='de'" html

Environment Information

Platform:              darwin; (macOS-13.1-x86_64-i386-64bit)
Python version:        3.10.8 (main, Oct 13 2022, 10:17:43) [Clang 14.0.0 (clang-1400.0.29.102)])
Python implementation: CPython
Sphinx version:        6.2.1
Docutils version:      0.19
Jinja2 version:        3.1.2
Pygments version:      2.14.0

Sphinx extensions

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autodoc.typehints",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinxcontrib.autodoc_pydantic",
    "nbsphinx",
    "sphinx_copybutton",
    "sphinx_panels",
    "IPython.sphinxext.ipython_console_highlighting",
]

mgeier commented 1 year ago

Thanks for reporting this!

I have never used Sphinx internationalization myself, but I remember an issue a few years ago (#154) which seems to have been solved with #156. After that, I haven't heard about any problems, but maybe nobody has used it since then?

Anyway, I tried to reproduce, but the dependencies of the example project made it too cumbersome for me.

Can you please provide a minimal reproducible example?

iamdalio commented 1 year ago

@mgeier
Thanks for your response. I did some debugging and it seems that there is an issue with the internationalization logic in Sphinx. The MD and RST files are ok , but processing the internationalization logic for the IPYNB files which are in JSON format generates error.I will contact the Sphinx team and let them know. nbsphinx is a great project, thank you.

mgeier commented 1 year ago

I don't think we should bother the Sphinx team at this point, I have the feeling that we can solve this on the nbsphinx side.

If you help me reproduce the problem, I can try to find the root cause and hopefully fix it.

OriolAbril commented 4 months ago

In case it helps, sphinx "marks" translated strings with <translated>. I saw there is currently a try/except, not sure if its goal is to catch only translations or other potential issues too.

What I would not know how to handle are the different types of cells allowed. It is clear they will no longer be json, but I don't know if when using gettext things get "translated" to rst (in which case always falling back to rst as is done now should never be an issue) or if that depends on the type of cell

spatialaudio / nbsphinx