Internationalization in Sphinx

Hi All,

Digging into the options for internationalizing As that is a sphinx build, research has led me here: Internationalization — Sphinx documentation

Somethings seem trivial: build to gettext, and then translate the PO files into the target language. This could be helpful for lots of users, especialmente nuestro grupo de idiomas españoles, and users from other languages.

But what do we do for languages that aren’t in this language list?:

Has anyone dealt with this before or have any insights? @danbjoseph or @pierotofy?


For example, say we had someone to translate into Kiswahili, I am unclear if we could just code this as SW and as long as we had all the appropriate files in the local_dirs or if we would need to wire things up specially.

Mm, that’s a good question; I’m not really sure about how Sphinx work, but I think that if you use an unsupported language, the language will show just fine in the content, but some sphinx items like menu names, buttons, etc. will not be labeled properly and default to English (I think that’s what they mean by “supported languages”). In that case you’ll want to contribute a translation for the unsupported language to Sphinx.

Got it. That makes sense. So we would want to contribute back translations for those kinds of items. In our case, that would be items like Search the docs and similar. Awesome. That helps.

I’ve thought about this a lot, especially when it comes to keeping things in sync across languages. I haven’t found a solution that I’m happy with. A rough concept note for a project I tried to get people to support:


It seems like a gap for sure. Was there any reason you saw to not piggy-backing on Sphinx? What are the limitations?

I guess for a workflow like you describe, it would be ideal if there was a whole workflow that triggered issues: updates pushed in one language trigger translations needed in another and so-forth.

The initial technical lift was a bit much and the projects I wanted to use it for ended up being just in Jekyll. I found a description of one person’s Sphinx workflow and it involved multiple custom scripts to run the whole update and push process?