2

I'm writing a project documentation in Sphinx. I want to make translations of my .rst files, and I generated and translated .po files. Sphinx generates html translations fine, but I want to have .rst or markdown full articles (to use them on another site).

How can I recreate .rst or markdown files with translations from these .po (or .mo) files?

Sphinx, gettext or Python solutions will suit. I tried to find information about that, but most answers concern translation of a string, not of a complete article.

Yaroslav Nikitenko
  • 1,695
  • 2
  • 23
  • 31
  • I found only one question, which asks about the same (https://stackoverflow.com/questions/17766089/apply-translation-using-gettext-po-files), but I wonder whether a better solution has appeared since 7 years, and whether there is a known solution for Sphinx. – Yaroslav Nikitenko Apr 16 '20 at 09:25
  • I prefer a general and "default" solution, but if it doesn't exist, then a script or 3rd party project is better than nothing. – Yaroslav Nikitenko Apr 16 '20 at 09:34
  • https://docs.readthedocs.io/en/stable/guides/manage-translations.html – Steve Piercy Apr 16 '20 at 09:57
  • @StevePiercy thanks, I just used that. But it generates html, not rst or markdown. This is the problem. – Yaroslav Nikitenko Apr 16 '20 at 10:00
  • I think you skipped over the part where it describes the process to create translatable messages using two methods in your documentation source files. – Steve Piercy Apr 16 '20 at 11:47
  • @StevePiercy sorry, I don't understand you. Could you please give a link to the exact subsection of the doc? In the beginning of your link the overview is "1) Create translatable files (.pot and .po extensions) from source language 2) Translate the text on those files from source language to target language 3) Build the documentation in target language using the translated texts" - it builds `html` docs, but there are no `rst` files in the process. I read this and another manual (https://docs.readthedocs.io/en/stable/localization.html), but didn't find the answer there. – Yaroslav Nikitenko Apr 16 '20 at 12:27

1 Answers1

1

I finally asked this question on the sphinx-users official mailing list. That one is really active and good. Matt from Documatt gave the following answer (with my small rewriting):

There is no direct way. Such a tool is on Docutil's todo list too. Just the idea that might help:

  1. Build your Sphinx to Docutils XML. For example, if you have French localization (fr), then

    sphinx-build -b xml source_dir output_dir -D language="fr"

    in your project root.

  2. Use Docutils's tool xml2rst.

The author of xml2rst also gave svn and sourceforge.net links to the code.

That worked indeed. There was a problem with extra whitespaces, however. They appeared during creation of the XML, and they threaten a well-formed rst (the xml2rst doesn't erase them). I'm going to delete them manually (this is not a big problem, any decent editor or sed can do that).

Yaroslav Nikitenko
  • 1,695
  • 2
  • 23
  • 31