-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
i18n (non-english) builds and deployment on readthedocs #139
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
Neat. I have been thinking about how to provide internationalization support. It isn't baked in anywhere on the backend, I just future-proofed the URLs because I didn't want to have to change them later :) I have some thoughts on how to do this, mainly it just involves modeling the relation from a master project to another project, and saying that it is the "it" translation of that. If you have any other thoughts on how to support this at a lower level, or with sphinx, I'd be curious. |
I'd suggest supporting this with sphinx since as mentioned sphinx now supports i18n "out of the box" (see http://sphinx.pocoo.org/intl.html). Of course a little bit of work is needed here but the good news is it's trivial and we worked most of this out for the Open Data Manual. Specifically from RTD point of view we need to:
The second item is pretty simple and is as follows (The following is just extracted from "Building a translation of the manual" in https://github.com/okfn/opendatamanual/blob/master/README.rst and associated make file): Let's assume we agreed translations always live in (this would either be hard convention of configurable in project settings):
Then all that would happen to build lang X would be:
Offer: if you point me in the right direction in the repo I could take a stab at coding some of this up ... |
Thanks for the info. This sounds pretty easy to accomplish. There are a couple problems that I'll probably need to deal with on my side, but it sounds like this shouldn't be too hard. The main problem is that the files are stored on disk without the translation in the directory hierarchy. This should be pretty easy to change, but will take a bit of time and scripting on our side. We namespaced the URLs, but not the filesystem, at least that's easier to change after the fact :) The sphinx builder is here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/sphinx.py - This and the base builder (in the same dir) are where most of that logic happens. It should just be figuring out how to get the language that is being built into the builder, and then making sure it ends up in the right directory on the file servers. I'd be willing to take a stab at helping get this done over the weekend, as it should be pretty simple, just a bit annoying. Cheers, |
@ericholscher great to hear this is possible. As you say once you introduce i18n you do get output namespaced with langs e.g. build/html/en/ build/html/it etc. If there is anything I can do let me know. |
Any update on this? I confirmed with my gntplib package in a local environment (gunicorn). http://localhost:8000/docs/gntplib/en/latest/ |
@papaeye can you submit a pull request with the patch? I imagine that would make it much easier for @ericholscher to review and incorporate. |
Anything new on this one? We're now starting to localize an API for Plone (github.com/plone/plone.api) and would love to have all languages on RTD. Is there anything I can help out with? |
Re: that PR -- I have merged it, but it doesn't address building python3 applications without a virtualenv. I am looking into how to support this, and will enable it on the site when it's done. |
Looking into it, when I install sphinx using python3 it doesn't install it as a seperate binary than with python2, so AFAICT I can only have 1 sphinx install (at least accessible by standard PATH commands). |
Believe this should be functioning now. We currently have people using multiple languages on RTD. Please file a new issue if there are outstanding issues. |
On standalone Sphinx installations I'm building
in #193 there was What is the status of ability to have non-English RTD translation project and still have only |
@myroslav have you created the new issue? |
readthedocs appears to have some intention to support different language builds of material as it puts 'en' into all urls :-)
However, I can't see from the readthedocs docs or the dashboard how to enable i18n builds or how to get deployed.
As a concrete use case we are building Open Data Manual in both english and other languages off of sphinx rest stored in github (see https://github.com/okfn/opendatamanual -- whose README details how we prep and build the i18n material):
We'd love to use readthedocs for this but need some way to have, for example, the 'it' version built and deployed. (We considered a hack approach by using the subproject feature but we imagined this would lead to urls like {subproject}/en/latest).
NB: i18n until recently was only in head for sphinx but as of v1.1 is now in main release.
Thanks again for creating such a great tool.
The text was updated successfully, but these errors were encountered: