Added localization language support #405

macagua · 2017-04-01T13:03:15Z

Added i18n support using Babel
Added Spanish translation
Updated .gitignore file

Blendify · 2017-04-01T14:01:00Z

Awesome IMO we should hold off on 0.2.5 until this gets merged.

Blendify · 2017-04-01T14:05:33Z

Once this gets merged I can talk to some of our translators and get the following translations:

De
Fr
It
Ja
Pt
Ru
Zh (Simplified)
Zh (Traditional)

mitya57

Please do not include the binary .mo files in the repository. Storing the binary files in Git is a bad idea, and this file is (re-)created by Sphinx during build anyway.
The .gitignore changes seem unrelated.

Once this is merged, I will be happy to provide a Russian translation. I have it ready already :)

macagua · 2017-04-02T15:05:26Z

@mitya57 you are right about .gitignore file I revert this commit :-)

mitya57 · 2017-04-02T15:26:09Z

It was better to rebase without that commit, rather than reverting.

But I am not the maintainer so I have no voice here anyway :)

macagua · 2017-04-03T12:48:39Z

@mitya57 please check out these improvements!

mitya57

Still adding the binary .mo file. Also, left an inline comment for setup.py changes.

mitya57 · 2017-04-03T12:52:28Z

setup.py

+        'Sphinx>=1.4.1',
+    ],
+    cmdclass = {
+        'compile_catalog': babel.compile_catalog,


If babel was not imported, this would be an undefined variable access. You can see this failure on Travis.

In my opinion setup.py modifications are not needed at all. This project is using setuptools, and babel is installing an entry point for setuptools, so these commands are available automatically.

@mitya57 it is the problem :(

then remove the Babel Distutils/setuptools integration? I had to install Babel via pip install so I could extract the strings to translate and compile the mo file.

When babel is installed, its setup.py commands should work automatically, without your changes to setup.py.

@mitya57 An good alternative will be create a requeriments-devs.txt file with the Jinja2 and Babel dependencies or create a TRANSLATE file with this instructions.

macagua · 2017-04-03T14:24:27Z

@mitya57 Removed sphinx.mo file 8f21fd0

… TRANSLATE file for more details about translate the package

macagua · 2017-04-03T14:57:42Z

@mitya57 done 👍

macagua · 2017-04-07T16:25:01Z

@mitya57 any update about this?

mitya57 · 2017-04-07T16:31:42Z

@macagua As I said, I am not the maintainer here, so someone else should merge this.

It looks good to me, though I would squash all commits into a single one to remove the useless changes (this can be done when merging though).

Blendify · 2017-04-07T21:32:54Z

LGTM

macagua · 2017-04-08T03:29:18Z

@mitya57 thanks you!!!
Maybe @agjohnson or @ericholscher can check and merge this improvement?

Blendify · 2017-04-08T03:54:21Z

Yes, I spoke with them today and they will have a look mid next week.

agjohnson

I noted some documentation changes, but otherwise I think this makes sense.

Our current workflow on RTD is to use Transifex. If there is anything here that competes with that, I'd rather update our process here to match.

agjohnson · 2017-04-10T18:58:39Z

README.rst

+============
+
+You can help to translate the Read the Docs Sphinx Theme,
+please check out the ``TRANSLATE.rst`` file for more details.


I'm -1 on littering the repo with these files, this should be in our documentation instead.

@agjohnson inside a docs directory with a Sphinx documentation format?

I think inside the demo docs. Are general idea is to make them include more information about the theme.

@Blendify inside demo_docs folder?

agjohnson · 2017-04-10T19:00:47Z

TRANSLATE.rst

+Languages availables:
+
+- Spanish contributed by Leonardo J. Caballero G.
+- Your Language by YOUR NAME.


This file should be moved into our docs. Also, I'm very happy to apply attribution, but putting author and translation status information in the docs is guaranteed to go stale. I'd rather avoid this and keep authors in another location.

@agjohnson @Blendify when you said "This file should be moved into our docs" are you refernce into the docs readthedocs.org? Or what kind of location are you preference? or what other location are you preference?

agjohnson · 2017-04-10T19:01:30Z

TRANSLATE.rst

+Installation
+============
+
+For translate the Read the Docs Sphinx Theme you need install the following packages:


For translate -> For translating

you need install -> you will need to install

@agjohnson done with commit 15d2198

agjohnson · 2017-04-10T19:02:03Z

TRANSLATE.rst

+
+.. code:: bash
+
+    $ pip install babel Jinja2


Jinja2 is a sphinx requirement and should already be present as part of development set up for this package.

@agjohnson I agree with you, but it is not clear when downloading this package so at least I indicate that dependencies minimally require to generate the gettext files with the Babel library from this package.

Remember that when you install this package using the command python setup.py install does not install any dependencies, ie. does not install Sphinx package.

@agjohnson Any news on this comment?

agjohnson · 2017-04-10T19:04:48Z

TRANSLATE.rst

+--------------
+
+It is available the option to init catalog. 
+More options please, check out http://babel.pocoo.org/en/latest/setup.html#update-catalog


This disutils section doesn't seem to clarify anything. It can either be dropped completely, or updated to be a list of explicit steps an author will need to take to create a translation.

Reverts fffca44

daonkim · 2018-11-19T04:07:51Z

Wow

macagua · 2019-01-22T21:42:29Z

@Blendify How can help to merge this improvements?

derdennis · 2019-02-23T19:57:14Z

Hello all,

I authored #587 almost a year ago and wanted to ask, if there is anything I can do to help with getting the proper internationalisation of this theme along? My impression is, that almost everything depends on this #405?

joerg-vandervlies · 2019-05-12T12:46:02Z

Hello everybody,

is anybody working on this merge request? I'd really appreciate to get this functionality.

kind regards
Jörg

derdennis · 2019-05-15T16:52:20Z

Hey Jörg,

is anybody working on this merge request? I'd really appreciate to get this functionality.

I don't know anything about the current work on this, but it is possible to use this functionality right now.

The folder locales in the source directory of your Sphinx project gets automagically searched for translations. If it is not there just create it. The needed structure looks like this:

source/locales/$LANG/LC_MESSAGES/sphinx.po

Where the $LANG part is a language identifier like it, ru or de.

If you want to use other folders than locales you can set the locale_dirs value in your conf.py as seen here.

I used this technique, copied in large parts from this comment, successfully with my German sphinx.po from here. The folder in locales is therefore named de.

Works like a charm.

joerg-vandervlies · 2019-05-15T21:18:14Z

Hi derdennis,

[...]
Works like a charm.

Yes, I found that exact solution in the meantime, too. It works indeed like a charm for the time being.
Thank you for outlining this temporary solution for others as well.

I can add a little bit of information: this solution also works well when using the latest sphinx-maven-plugin

thank you again
Jörg

macagua · 2019-05-22T20:31:09Z

THE STATE OF THIS PULL REQUEST

Hi guys, this improvement a time ago, it worked very well and it happened with the review of many guys here, in it moment, just a new Sphinx package release was needed to make merge into sphinx_rtd_theme theme, but the time pass and these changes dont work again because it is out of date with the base branch, then it will need to give it time and write the code for it can be accepted and merged, I hope in the next weeks dedicate time to this update this improvement.

P.D .: Really I hope in this time, the imporvements can be pass and merge more faster that in the past.

agjohnson · 2019-06-19T01:31:54Z

For me, the main problem holding this PR back is the documentation. Frankly, it's too dense of a guide for our package. I don't think we need this amount of depth in our own documentation.

Here's Sphinx's contributor guide for comparison:
http://www.sphinx-doc.org/en/master/devguide.html#locale-updates

I'd prefer if ours was similarly brief and easy to digest, otherwise folks won't know what to do with translations (myself included). I understand that maybe a guide that is sufficiently thorough is missing from the Babel community, but I don't think this package is the place to explain these concepts.

Ultimately, Read the Docs uses Transifex for all of our translations, and we'll move this package into our Transifex pattern as soon as it's ready. This masks the need to know how gettext tooling works under the hood -- including mo, po, and pot files -- and hopefully this is a lot easier for translators.

We'll have more time scheduled towards this and Sphinx 2 compatibility next month, but I can say that I'm 👍 on babel usage and most of the changes here. For me, it's simply the documentation where I get lost at and a bit overwhelmed. If we can dial this PR back on docs, this PR will be about ready to merge.

And thanks @macagua for sticking with this PR! I'm sorry this has been mostly off our roadmap for a long while, but we'll get back to guiding this a bit more as we focus on Sphinx 2 compatibility.

This builds on top of #405, addressing the outstanding review feedback. It: * Moves workflow to our standard Transifex workflow, drops recommendation for running babel commands by hand * Configures Transifex * Moves all of the commands needed to maintain translations into Grunt * Sets up docs for translation testing * Covers installation in docs better * Drops recommendation for installation through submodules * Drops superfluous translation documentation * Cleans up some of the code * Updates a lot of related documentation * Updates files at Transifex and brings in full translations back to the translation files in the repository

agjohnson · 2019-07-17T02:38:00Z

I've moved to addressing the outstanding PR feedback in #778. I automated more of the operations and removed the documentation on manually running babel commands. I'll aim to merge #778 into a common branch, and then deal with rebasing on master after.

agjohnson · 2019-07-25T19:24:37Z

This work was merged in #793 🎉

Thanks again to @macagua for the effort and guidance on this, I'm quite happy with the pattern and I think Babel finally makes sense to me. This is now also a reproducible pattern for some of our other packages.

If you are interested in translating, be sure to visit https://www.transifex.com/readthedocs/sphinx-rtd-theme

We're happy to have translators and reviewers added to teams there and the number of strings to translate is very manageable.

NicolasCaous · 2020-03-31T19:37:46Z

How do I configure my project to use the translation feature mentioned in this issue?

I have my conf.py setting the language variable like so: language = 'pt_BR', but the theme isn't translating.

It still shows up like this:

Built with Sphinx using a theme provided by Read the Docs.

But I was expecting something like this:

Contruído com Sphinx usando um theme fornecido por Read the Docs.

However, some of the content is translated (I guess what is not in the theme but in Sphinx itself is being translated).

Can someone help a poor soul?

derdennis · 2020-04-10T06:54:27Z

Hey, Nicolas,

it seems my answer from May 2019 still holds true:

I don't know anything about the current work on this, but it is possible to use this functionality right now.

The folder locales in the source directory of your Sphinx project gets automagically searched for translations. If it is not there just create it. The needed structure looks like this:
source/locales/$LANG/LC_MESSAGES/sphinx.po
Where the $LANG part is a language identifier like it, ru or de.

If you want to use other folders than locales you can set the locale_dirs value in your conf.py as seen here.

I used this technique, copied in large parts from this comment, successfully with my German sphinx.po from here. The folder in locales is therefore named de.

Works like a charm.

I guess it did not work with the theme part for you, because there is no Portuguese translation folder, neither pt nor pt_br available in the locale-folder of the rtd_theme right now. You could try with nl or ru and check if everything turns Dutch or Russian and then add the Portuguese translation.

Hope that helps!

macagua added 2 commits April 1, 2017 08:35

Updated .gitignore file

ea89880

Added i18n support using Babel and Spanish translation

7dadea5

agjohnson added the PR: ready for review label Apr 1, 2017

macagua mentioned this pull request Apr 1, 2017

Add localization language support #403

Closed

mitya57 suggested changes Apr 1, 2017

View reviewed changes

Revert commit ea89880

be27427

Updated way how import babel library to use for as command class options

4cff61f

mitya57 suggested changes Apr 3, 2017

View reviewed changes

Removed sphinx.mo file

8f21fd0

Removed Sphinx and Babel command class from setup.py file and added a…

3329e09

… TRANSLATE file for more details about translate the package

agjohnson reviewed Apr 10, 2017

View reviewed changes

agjohnson added PR: work in progress Pull request is not ready for full review and removed PR: ready for review labels Apr 13, 2017

macagua and others added 2 commits April 14, 2017 10:54

Check spell

15d2198

Merge branch 'master' into master

fc9dfa5

readthedocs deleted a comment Jun 18, 2017

Blendify added 3 commits November 5, 2018 10:38

Update changelog.rst

cd34154

Remove bad import

fffca44

Revert change

ab89bb1

Reverts fffca44

theacodes mentioned this pull request Feb 19, 2019

Make copybutton messages translatable python/python-docs-theme#27

Open

Blendify added 4 commits March 6, 2019 10:18

Delete requirements.txt

8ac4638

Remove requirements file thats not needed

8992188

Merge branch 'master' into master

7050db0

Update .travis.yml

f9a2fe4

agjohnson changed the title ~~Added localization language support #403~~ Added localization language support Jul 16, 2019

agjohnson mentioned this pull request Jul 17, 2019

Continuation of adding translations to theme #778

Closed

agjohnson mentioned this pull request Jul 25, 2019

Finalized addition of theme localization #793

Merged

agjohnson merged commit f9a2fe4 into readthedocs:master Jul 25, 2019

agjohnson mentioned this pull request Jul 25, 2019

Swap to using webpack #771

Merged

blueset mentioned this pull request Jan 18, 2020

Sidebar titles not localized sphinx-doc/alabaster#71

Open

Blendify modified the milestones: 1.1, 1.0 Apr 11, 2021

Added localization language support #405

Added localization language support #405

Conversation

macagua commented Apr 1, 2017

Blendify commented Apr 1, 2017

Blendify commented Apr 1, 2017

mitya57 left a comment

Choose a reason for hiding this comment

macagua commented Apr 2, 2017

mitya57 commented Apr 2, 2017

macagua commented Apr 3, 2017

mitya57 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

macagua commented Apr 3, 2017

macagua commented Apr 3, 2017

macagua commented Apr 7, 2017

mitya57 commented Apr 7, 2017

Blendify commented Apr 7, 2017

macagua commented Apr 8, 2017

Blendify commented Apr 8, 2017 via email

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daonkim commented Nov 19, 2018

macagua commented Jan 22, 2019

derdennis commented Feb 23, 2019

joerg-vandervlies commented May 12, 2019

derdennis commented May 15, 2019

joerg-vandervlies commented May 15, 2019

macagua commented May 22, 2019

agjohnson commented Jun 19, 2019

agjohnson commented Jul 17, 2019

agjohnson commented Jul 25, 2019

NicolasCaous commented Mar 31, 2020

derdennis commented Apr 10, 2020