[Numpy-discussion] Internationalization of numpy/scipy docstrings...

Ralf Gommers ralf.gommers at googlemail.com
Mon May 21 17:44:28 EDT 2012


On Sun, May 20, 2012 at 11:59 PM, Tim Cera <tim at cerazone.net> wrote:

> Are you thinking only about documentation in .rst files (like the
>> tutorials), or also the docstrings themselves? The former may be feasible,
>> the latter I think will be difficult.
>>
>>
> Everything.  Within the documentation editor the RST docstrings are parsed
> from the functions, so instead of only storing them in the database for
> Django/doceditor to work with, can save them to *.rst files.
>
> I don't know how integrated we could/would make the documentation
> editor/sphinx/pootle combination, so I think the easiest would be
> integration through files.  Your question points out a detail (and some
> small refinements) that I should have put in the outline from my first
> message:
>
>   0.5. As the pydocweb editor works on docstrings, up-to-date RST files
>          are also saved to the file system, and triggers...
>
>   1. The new gettext builder to convert *.rst to *.pot files.
>
>   1.5. (OPTIONAL) Can make a preliminary, automatic translation.  Pootle
>
>         currently supports Google Translate (now costs $) or Apertium.
>
>   2. Translators would use pootle to edit the *.pot files to *.po files
>
>   2.5. Use mgsfmt to create *.mo files
>
>   3. From here can choose either:
>
>       a. Use sphinx-build to create new,
>
>          translated *.rst files from the *.mo files.
>
>          (my favorite since we would have *.rst files)
>
>       b. OR use gettext in Python to translate docstring
>
>          on-the-fly from the *.mo files.
>
>
>
Docstrings are not stored in .rst files but in the numpy sources, so there
are some non-trivial technical and workflow details missing here. But
besides that, I think translating everything (even into a single language)
is a massive amount of work, and it's not at all clear if there's enough
people willing to help out with this. So I'd think it would be better to
start with just the high-level docs (numpy user guide, scipy tutorial) to
see how it goes.

Thinking about what languages to translate into would also make sense,
since having a bunch of partial translations lying around doesn't help
anyone. First thought: Spanish, Chinese.

Ralf



> At this point we would need to have an environment variable or other
> configuration mechanism to set the desired locale, which np.info would
> use to find the correct directory/rst file.  Lets just say for sake of my
> example that the configuration is handled by a np.locale function.
>
>
>   np.info(np.array)
>
>   # display English docstring as it currently does
>
>
>   np.locale('fr')
>
>   np.info(np.array)
>
>   # display the French docstring
>
>
> Reference links:
>
> sphinx based translation
>
>   http://sphinx.pocoo.org/latest/intl.html
>
>   http://www.slideshare.net/lehmannro/sphinxi18n-the-true-story
>
> Pootle:
>
>   http://translate.sourceforge.net/wiki/pootle/index
>
>   (You have to get the development versions of translate and pootle to
> work with Django 1.4.)
>
>
> Kindest regards,
>
> Tim
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20120521/724b9a5a/attachment.html>


More information about the NumPy-Discussion mailing list