[FEATURE] Add Per Page Internationalization

[marble]

With these additions single pages and single posts can be rendered in a different language. Specify the language in the post directive or in the documents metadata.

Find a complete description in my new blog ( : - )) which exactly is the use case for the new feature: http://mbless.de.local/blog/2014/09/19/ablog-per-page-i18n.html

Yippieh!

[abakan-zz]

Hi Martin, I don't quite understand what these changes do. Does it create copy of .html pages with navigation labels in a second language and content in the original language? Or, is it for translating a document from one language to another? Could you explain me please? Thanks.

[marble]

Yes, of course, I gladly try to give a detailed explanation at http://mbless.de/blog/2014/09/20/ablog-i18n.html The essence is: By default Sphinx does no translation at all. But you can tell Sphinx to do so. Adding - for example - language=de to the settings in :file:conf.py will make Sphinx translate the builtin text constants to german. That's great, but you can only specify one language which will then be applied to all pages and all posts.

What if only some pages and some posts have a different language? That's what I want to solve with the proposed additions. They let you specify a translation language on a "per post" or "per page" basis.

[abakan-zz]

Ok, I see now what per page internationalization is.

I thought of :language: as an option to aggregate posts in different languages into corresponding language archive pages. With this change, when :language: option is used constant text in that page will be automatically translated. This may not be what everyone wants, I imagine. Someone may prefer building entire Sphinx project in different languages and having two versions of the entire website.

To avoid this side effect and to make this work the same way for posts and non-post pages, I would suggest these changes:

• Use :language: de, or :htmllang: de as in non-post pages.
• Move the code that is in Blog.__init__, into another function, or a class. A class as a singleton may be better, and let's call it Translator.
• When html_page_context encounters :language: de option, it asks Translator to load the translator for that language, and edits the context for translation.

What do you think?

[marble]

Thank you for taking your time and answering so quickly. I didn't find enough time yet but at least want to come back with a response here. I see three different aspects: One is about: What option, what confval should mean exactly what? This probably needs a bit more clarification and some decisions.

The next aspect is about how to code it. Yes, why not have a "Translation" class. I understand your wish for making this separate.

A third aspect is more a less a question of mine: Why are you doing this "trick" with making the Blog class a singleton? A clear and obvious solution would be IMHO: Instantiate ONE Blog isntance during the setup and attach that to the app like "app.ablog = Blog()". From then on use "app.ablog" to reach our one and only instance.

So, I need a bit more time atm and will then come back. Have a nice day!

[abakan-zz]

I guess I didn't need Blog instance to be an app attribute. In the beginning, I had app.ablog = Blog() and also env.ablog = Blog(), but having it as env attribute caused problems with pickling the environment. So, I just kept a dictionary of lists with postinfo in env to overcome pickling issue and with all the changes I needed to make I did not need app.ablog. Now, a class whose instances share a single state work fine. I don't remember all the details that drove me to this design choice though. You too have a nice day :)

[marble]

A simple solution has come into my mind (I think...). The logic would be:

1. By default Sphinx uses English for text constants.
2. If language = 'nn' is in conf.pySphinx turns translation to 'nn' ON for ALL pages
3. New feature, my proposal: if :language: 'xy' is in the document's metadata Sphinx translates language constants to 'xy' for THAT specific page.
4. New idea: The same is true for posts. If you want a different output language for that post, specify that in the document's metadata.
5. The :language: option of a post has nothing to do with output translation.

As a result the whole "per page translation stuff" has nothing to do ABlog anymore. So I can code that in a separate and independent Sphinx extension.

How about that? Will make you happy, I guess :-)

[abakan-zz]

I think this is a simple yet very good design. It may become a separate extension, but if you want it to be distributed with ABlog, I will be happy to do so. I plan to start unit testing ABlog API and then document it for template designers. That will probably be the next release in a week or two, in case you want this to go out with it.

[marble]

A few days have past and I'm a bit wiser now. Let me start with the conclusion: I think it's best to just close this pull request and don't merge anything. But many thanks for being open to these ideas!

Details: Enriching the render context ctx with the gettext() functions works and will affect the translations in the templates. But unfortuneately the contents of a page has already been rendered BEFORE we come to this hook. So for example admonitions don't get translated. And unfortunately there is no builder event saying "Now the next document 'docname' is going to be rendered" that I could hook into. And I don't want to sublass the builder or writer classes. And therefore I don't see a really clean and easy general solution at the moment.

And with the notion of specifying the language in the documents metadata there is no need to mix this functionality into ablog. So you shouldn't do it.

The current status is: I have moved the functionality into a separate Sphinx extension 'sphinxcontrib.langpp'. I plan to upload that extension in the near future somewhere to make it open for discussion. I'll let you know when I do. At the moment it's still a bit experimental. Personally I have resorted to using a (Python) postprocessor that uses BeautifulSoup and rearranges things in the HTML outfile.

[abakan-zz]

That sounds good. Thanks Martin.