Let's translate the official docs!

[Eduardo Rivas]

Hello everyone. I've been speaking with another member of the Spanish-speaking Mezzanine community (Jesús Anaya) and he came up with several ideas to boost Mezzanine's popularity in said language, one of which is translating the official docs. Of course, this opens the gates for other languages too and I believe it'll mark a milestone for Mezzanine as a project.

My questions are:

• Are there other developers in other languages interested in translating the docs?
• How should we do this? Separate repos? PRs to Steve's repo?
  

Any advice in documentation-writing in general is welcome :) Thanks!

[Stephen McDonald]

Sounds awesome - I think translated docs belong in the repo along with the original docs. I'd simply merge any PRs that come through as I do with other translation contributions. 

One thing that would need solving is how to generate the static version of the docs in multiple languages with some kind of language switcher.

--
You received this message because you are subscribed to the Google Groups "Mezzanine Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mezzanine-use...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
Stephen McDonald
http://jupo.org

[Eduardo Rivas]

I don't have experience with Sphinx, but I found this. Apparently you can generate translation catalogs in gettext, so we could use Transifex as we already do with Mezzanine. Here is a blogpost with a quick overview of the process and some scripts for automating the process of generating the files.

[Andrzej Grymkowski]

I may try in translate the docs to Polish. 

[Diego Ponci]

I'd be more than happy to help with Portuguese (Brazilian) translations.

[Stephen McDonald]

Thanks a lot Ed for kicking this off, and thanks to everyone for all the translation offers! This is really exciting.

I've started off by skimming the resources Ed mentioned and I think I've come up with an initial workflow. It looks very similar to how we currently translate all the strings in Mezzanine itself. First up I've made some tweaks here that just adds the right config bits in place and ignores any files that are generated as part of the translation process: https://github.com/stephenmcd/mezzanine/commit/e3a96441ff25f865300d53411f36ac0696d3525a

So with an up-to-date copy of the repo, the steps so far seem to be as follows:

$ pip install sphinx sphinx-intl <-- install these packages

$ cd docs <-- run the next commands from within the docs dir

$ sphinx-build -b gettext . locale <-- generates all the .pot files that convert the docs into individual translatable strings

$ sphinx-intl update -p locale -l es <-- generates all the .po files (like with Django) for the "es" locale, these are the files you edit/commit

In case it's not obvious, don't run all the above literally, I commented each line prefixed with "<--". Once we have the first language done, I'll work out the remaining process for generating HTML and hosting all the languages on the project site with some kind of language chooser.

PS: My opinion would be to not bother with transifex at this stage - it's caused problems with Mezzanine so far in that people (including myself) are confused about the process, whether they have to use it or can just commit directly to the repo, when do translations go from transifex to the repo, does the reverse need to happen, etc. It's just one big extra mental dependency and I feel like the convenience in actually doing the translations (web interface vs text files) outweighs the overhead.

--

You received this message because you are subscribed to the Google Groups "Mezzanine Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mezzanine-use...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Eduardo Rivas]

Thanks a lot Steve for setting everything up! I'll give it a shot as
soon as I can.

[Eduardo Rivas]

Ok, so I got some free time and started working on this. I have now generated all the .po files and completely translated one of them. I created a pull request for Steve and others to see how it's coming. What are the next steps after translating the .po files? How can I build and test the docs locally?

[Stephen McDonald]

Awesome! I'll try and work out how to build html from that shortly.

On Thu, Aug 21, 2014 at 9:47 AM, Eduardo Rivas <jeriva...@gmail.com> wrote:

Ok, so I got some free time and started working on this. I have now generated all the .po files and completely translated one of them. I created a pull request for Steve and others to see how it's coming. What are the next steps after translating the .po files? How can I build and test the docs locally?

--

You received this message because you are subscribed to the Google Groups "Mezzanine Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mezzanine-use...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Eduardo Rivas]

By the way, the page I've translated so far is "Admin Customization".

You received this message because you are subscribed to a topic in the Google Groups "Mezzanine Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/mezzanine-users/4o104Uohg2E/unsubscribe.
To unsubscribe from this group and all its topics, send an email to mezzanine-use...@googlegroups.com.