I18nreshuffle

[Ivoz]

Allthough the recent translation is awesome work, I am intending to rewrite some of the tutorial for Melbourne's meetup tomorrow, and this work didn't seem reproduceable to me or in line with sphinx's suggested method of constructing i18n translation.

I have rejigged the project to make the file structure simpler, the fabfile to expand its capabilities (do all necessary steps to work on translating), and redone the i18n.

Unfortunately this means the current translations will need to be moved and split into the new homes, but this should make it far more maintainable in the future for translators. If one file changes in the main source, you can use the fab file to update the changes and then go into the corresponding po file and update the translations.

Please read the associated commit message for more details as well.

Being a stickler for cleanliness, I had to do this before updating the wording in the tutorial proper >_>

Let me know what you think.

[lehmannro]

Just a quick note (I have not looked at your changes in-depth): I built the message catalogs with an experimental version of Sphinx which has not yet been released (or, pushed, for that matter.) I thought having one single catalog for the whole workshop makes more sense.

[benoitbleuze]

Amen to cleanliness and modularity: having more translation files is always a good idea to me.

• that was my useless contribution to this discussion, but being a stickler for modularity, I had to support your effort here -

Ben

On 20 September 2013 11:39, Matt Iversen notifications@github.com wrote:

Allthough the recent translation is awesome work, I am intending to rewrite some of the tutorial for Melbourne's meetup tomorrow, and this work didn't seem reproduceable to me or in line with sphinx's suggested method of constructing i18n translation.

I have rejigged the project to make the file structure simpler, the fabfile to expand its capabilities (do all necessary steps to work on translating), and redone the i18n.

Unfortunately this means the current translations will need to be moved and split into the new homes, but this should make it far more maintainable in the future for translators. If one file changes in the main source, you can use the fab file to update the changes and then go into the corresponding po file and update the translations.

Being a stickler for cleanliness, I had to do this before updating the wording in the tutorial proper >_>

Let me know what you think.

You can merge this Pull Request by running

git pull https://github.com/OpenTechSchool/python-beginners i18nreshuffle

Or view, comment on, or merge it at:

https://github.com/OpenTechSchool/python-beginners/pull/42 Commit Summary

• Update index to include de version
• Major reshuffle, reproduceable i18n

File Changes

• M .gitignorehttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-0(5)
• M README.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-1(29)
• A _static/index.htmlhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-2(35)
• D docs/_static/index.htmlhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-3(28)
• D docs/en/conf.pyhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-4(13)
• D docs/fabfile.pyhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-5(51)
• A fabfile.pyhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-6(102)
• M requirements.txthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-7(1)
• R source/_locales/de/LC_MESSAGES/pybeginners.mohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-8(0)
• R source/_locales/de/LC_MESSAGES/pybeginners.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-9(0)
• R source/_static/spoilers.jshttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-10(0)
• R source/_templates/layout.htmlhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-11(0)
• R source/conditional_loops.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-12(0)
• R source/conditionals.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-13(0)
• R source/conf.pyhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-14(3)
• R source/copyright.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-15(0)
• R source/functions.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-16(0)
• R source/functions_parameters.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-17(0)
• R source/getting_started.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-18(0)
• R source/images/cc-by-sa.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-19(0)
• R source/images/dashed.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-20(0)
• R source/images/dashedprogressing.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-21(0)
• R source/images/default.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-22(0)
• R source/images/floorplan.jpghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-23(0)
• R source/images/forward.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-24(0)
• R source/images/hexagon.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-25(0)
• R source/images/honeycomb.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-26(0)
• R source/images/house.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-27(0)
• R source/images/it_uni_copen_2.jpghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-28(0)
• R source/images/left.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-29(0)
• R source/images/ots_logo_fb.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-30(0)
• R source/images/ots_logo_v.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-31(0)
• R source/images/progress.gifhttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-32(0)
• R source/images/rectangle.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-33(0)
• R source/images/square.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-34(0)
• R source/images/tiltedsquares.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-35(0)
• R source/images/triangle.pnghttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-36(0)
• R source/index.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-37(0)
• A source/locale/de/LC_MESSAGES/conditional_loops.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-38(118)
• A source/locale/de/LC_MESSAGES/conditionals.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-39(136)
• A source/locale/de/LC_MESSAGES/copyright.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-40(29)
• A source/locale/de/LC_MESSAGES/functions.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-41(150)
• A source/locale/de/LC_MESSAGES/functions_parameters.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-42(94)
• A source/locale/de/LC_MESSAGES/getting_started.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-43(260)
• A source/locale/de/LC_MESSAGES/index.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-44(20)
• A source/locale/de/LC_MESSAGES/logical_operators.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-45(85)
• A source/locale/de/LC_MESSAGES/loops.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-46(113)
• A source/locale/de/LC_MESSAGES/simple_drawing.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-47(199)
• A source/locale/de/LC_MESSAGES/variables.pohttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-48(111)
• R source/logical_operators.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-49(0)
• R source/loops.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-50(0)
• R source/simple_drawing.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-51(0)
• R source/variables.rsthttps://github.com/OpenTechSchool/python-beginners/pull/42/files#diff-52(0)

Patch Links:

• https://github.com/OpenTechSchool/python-beginners/pull/42.patch
• https://github.com/OpenTechSchool/python-beginners/pull/42.diff

[Ivoz]

I followed the recommendations from the sphinx documentation and from the package sphinx-intl to construct this.

Checking out the fab file should also give a good idea for the process (good learning exercise for me about i18n!).

Sphinx' docs follow a process which creates separate catalogue files, so one master catalogue does not need to change every time any source file changes, only the catalogue associated with the source file.

I would be interested to know about where to find [about] the process in the dev sphinx version, and read if that process differs a lot from the one currently in the official docs.

[lehmannro]

I'm not sure in how far modularity is really an argument for mostly auto-generated files. Also, it's much easier to just upload one file to Transifex than a collection of them. If we're changing one small file in version control or one big one is not really a difference as well, right?

There process for that compact translation file is not really different from the one currently in released Sphinx. It's mainly a convenience patch.

[Ivoz]

The latest sphinx documentation is here:

http://sphinx-doc.org/latest/intl.html

Mutliple pot files is also what the sphinx gettext command generates, so it's an extra step to merge them. As far as I can see it's still generating multiple pot files in the master version on bitbucket...

You can use sphinx-intl and the transifex client to automatically upload them to transifex.

http://sphinx-doc.org/latest/intl.html#using-transifex-service-for-team-translation

I really don't see a reason to differ from the default way sphinx generates and handles them

[lehmannro]

When I originally designed that feature in Sphinx having one catalog per file was just one arbitrary choice. I now think a consolidated file per project, not per project-section, makes sense.

On Sat, Sep 21, 2013 at 4:32 PM, Matt Iversen notifications@github.comwrote:

The latest sphinx documentation is here:

http://sphinx-doc.org/latest/intl.html

Mutliple pot files is also what the sphinx gettext command generates, so it's an extra step to merge them. As far as I can see it's still generating multiple pot files in the master version on bitbucket...

You can use sphinx-intl and the transifex clienthttps://pypi.python.org/pypi/transifex-clientto automatically upload them to transifex.

http://sphinx-doc.org/latest/intl.html#using-transifex-service-for-team-translation

I really don't see a reason to differ from the default way sphinx generates and handles them

— Reply to this email directly or view it on GitHubhttps://github.com/OpenTechSchool/python-beginners/pull/42#issuecomment-24863433 .

[lehmannro]

Also, don't get me wrong: I don't want to make a fuss about auto-generated file names and agree the python-beginners repository needs a reorganization. However, I think we need a clean migration path and just throwing away all translations is unacceptable.

[Ivoz]

I can add some commits to update the pos with the existing translations as soon as I get some time

[Ivoz]

I have updated the pos to contain the current translations.

I now think a consolidated file per project, not per project-section, makes sense.

Can you elucidate/convince me on why? It seems to me a somewhat arbitrary decision, intuitively I'd swing towards breaking things up as it lets different people work on different files concurrently and a file usually relates to one topic, making things easy to digest. But hearing that you've done a lot of work on sphinx translation I'm imagining you have some reasoning as to why you think differently.

Unfortunately a working process for making compiled po's is not in sphinx yet (that you were thinking of pushing?), but we do have a tutorial that's currently up and running :/

[lehmannro]

Thanks for updating them, if nobody beats me to it I'll try to have a look at the patch this week.

As for message catalogs, I agree it is an arbitrary decision. I think it is more useful — and also more common, as far as I remember — to have one catalog per product (say, sphinx.pot, instead of having sphinxcore.pot and sphinxbuilders.pot and sphinxdomains.pot and so forth.) The original design of the feature was based on the official Python documentation, which is basically a couple of different products: the Library Reference, the Language Reference, the Tutorial, etc. There is currently the gettext_compact setting, which aims to suit all kind of product suites. I plan on extending this attribute in Sphinx 1.2 to support very tight bundling as well.

A process of compiling message catalogs is currently not included in Sphinx, and that's unfortunate. I seem to remember there has been a Pull Request (on Sphinx) for adding such features to the Makefile and you have already discovered sphinx-intl. I want to integrate one of these into Sphinx in the future, but there's no ETA.

[Ivoz]

This is the script I used to do the translation redistribution

https://gist.github.com/Ivoz/6675429