Is Django documentation translations to land in main repository ?

[Amirouche B.]

Héllo,

Everything is in the title. Does Django core dev's want to have localized documentation in main repository or should it be managed by local DUG ?

Thanks to Pilot Systems, I improved a bit the french documentation [1] basically what I've done is converted it to use the Sphinx support of .po files and translated the how-tos.

Now what main repo needs:

- fix the Makefile [2] like it's done in [1] or something smarter maybe convert the Makefile to a Python script so that we have a better handling of locales please see [2]

- the source documentation needs some fixes to be fully possible to do L10N but it's not a priority (problems might be solved in Sphinx)

Mind the fact that getting .po support and the facility to do documentation L18N in the main repo is needed to avoid any future effort to do what is IMO a mistake to translate the documentation in the rst files.

What do you think ?

Thanks.

[1] https://bitbucket.org/amirouche/django-fr-translation

[2] https://bitbucket.org/birkenfeld/sphinx/issue/1026/makefile-for-building-mo-and-merging-po

[Russell Keith-Magee]

On Sat, Dec 15, 2012 at 11:53 AM, Amirouche B. <amirouche...@gmail.com> wrote:

Héllo,

Everything is in the title. Does Django core dev's want to have localized documentation in main repository or should it be managed by local DUG ?

Yes :-)

In a perfect world, you'd be able to get documentation in other languages on docs.djangoproject.com. If you look at the URL space, you'll see that we've already prepared for translations -- you hit /en/dev to get the development docs; in theory, we could serve /fr/dev for french documentation.

However, what we're missing is the process for managing these translations.

The core team speak a few languages (we've got German, French and Spanish covered, and possibly a couple of others), but aren't in a position to review and commit revisions for lots of other significant languages. 

Taking i18n and l10n as an example; we've moved to using Transifex specifically because it allows us to give control of translations to local language communities; then, once per release, we push a single commit of translation updates to the main repository. Ideally, we'd take a similar approach for translated docs, but Transifex isn't really well suited to translation of large bodies of text.

So - your translation efforts are definitely welcome. What we need to work out is the process by which we can practically use these translation efforts -- and, more importantly, make sure that they're kept up to date (e.g., once a base translation is done, ensuring that translation teams have a 'todo' list, and we can indicate to readers which translations are current, and which are stale). Any suggestions on how we could manage this are also welcome.

Yours,

Russ Magee %-)

 

Thanks to Pilot Systems, I improved a bit the french documentation [1] basically what I've done is converted it to use the Sphinx support of .po files and translated the how-tos.

Now what main repo needs:

- fix the Makefile [2] like it's done in [1] or something smarter maybe convert the Makefile to a Python script so that we have a better handling of locales please see [2]

- the source documentation needs some fixes to be fully possible to do L10N but it's not a priority (problems might be solved in Sphinx)

Mind the fact that getting .po support and the facility to do documentation L18N in the main repo is needed to avoid any future effort to do what is IMO a mistake to translate the documentation in the rst files.

What do you think ?

Thanks.

[1] https://bitbucket.org/amirouche/django-fr-translation

[2] https://bitbucket.org/birkenfeld/sphinx/issue/1026/makefile-for-building-mo-and-merging-po

--
You received this message because you are subscribed to the Google Groups "Django developers" group.
To view this discussion on the web visit https://groups.google.com/d/msg/django-developers/-/r5vbKm3wovEJ.
To post to this group, send email to django-d...@googlegroups.com.
To unsubscribe from this group, send email to django-develop...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.

[Amirouche B.]

On Saturday, December 15, 2012 5:05:36 AM UTC+1, Russell Keith-Magee wrote:

On Sat, Dec 15, 2012 at 11:53 AM, Amirouche B. <amirouche...@gmail.com> wrote:

Héllo,

Everything is in the title. Does Django core dev's want to have localized documentation in main repository or should it be managed by local DUG ?

Yes :-)

In a perfect world, you'd be able to get documentation in other languages on docs.djangoproject.com. If you look at the URL space, you'll see that we've already prepared for translations -- you hit /en/dev to get the development docs; in theory, we could serve /fr/dev for french documentation.

Cool, didn't noticed 

 

However, what we're missing is the process for managing these translations.

The core team speak a few languages (we've got German, French and Spanish covered, and possibly a couple of others), but aren't in a position to review and commit revisions for lots of other significant languages. 

Taking i18n and l10n as an example; we've moved to using Transifex specifically because it allows us to give control of translations to local language communities; then, once per release, we push a single commit of translation updates to the main repository. Ideally, we'd take a similar approach for translated docs, but Transifex isn't really well suited to translation of large bodies of text.

So - your translation efforts are definitely welcome. What we need to work out is the process by which we can practically use these translation efforts -- and, more importantly, make sure that they're kept up to date (e.g., once a base translation is done, ensuring that translation teams have a 'todo' list, and we can indicate to readers which translations are current, and which are stale). Any suggestions on how we could manage this are also welcome.

I never used Transifex, I don't know why this can not be used for large projects. Maybe it can work ? 

Here is what I propose:

- A manager is choosed among every LUG to manage a Transifex project for its langage

- Once every release or every 6 months POs are pushed to main repo

- If the L10N effort lakes behind the releases, users are notified that the documentation is not available in their language and propose a) to go to old doc b) to go to english doc (I don't think this is handled by readthedocs so this is another issue)

The manager (or the managing team) will have in charge to update PO files on Transifex in a regular fashion.

Maybe someone with Transifex experience can tell more about that.

Another option I think of, is to break documentation directory and maybe even each locale directory into a git submodule so that LUGs can work on translation without polluting the main git history with L10N stuff while still being able to use git to manage the translation which will also allow to avoid having to use Transifex.

Looking forward having other insights about this issue.

Regards,

Amirouche