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

josef.pktd at gmail.com josef.pktd at gmail.com
Tue May 22 12:46:44 EDT 2012

On Tue, May 22, 2012 at 10:51 AM, Tim Cera <tim at cerazone.net> wrote:
>> 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.
> I understand that this is non-trivial, for me anyway, because I can't figure
> out how to make my way around numpydoc, and documentation editor code (not
> quite true, as Pauli accepted a couple of my pull requests, but
> I definitely can't make it dance).  This is why I asked for interest and
> help on the mailing list.  I think for the people that worked on the
> documentation editor, or know Django, or are cleverer than I, the required
> changes to the documentation editor might by mid-trivial.  That is my hope
> anyway.
> Would probably have the high-level docs separate from the docstring
> processing anyway since the high-level docs are already in a sphinx source
> directory.  So I agree that the high-level docs would be the best place to
> start and in-fact that is what I was working with and found the problem with
> the sphinx gettext builder mentioned in the original post.
> I do want to defend and clarify the docstring processing though.
>  Docstrings, in the code, will always be English. The documentation editor
> is the fulcrum.  The documentation editor will work with the in the code
> docstrings exactly as it does now.  The documentation editor would be
> changed so that when it writes the ReST formatted docstring back into the
> code, it also writes a *.rst file to a separate sphinx source directory.
>  These *.rst files would not be part of the numpy source code directory, but
> an interim file for the documentation editor and sphinx to extract strings
> to make *.po files, pootle + hordes of translators :-) gives *.pot files,
> *.pot -> *.mo -> *.rst (translated).  The English *.rst, *.po, *.pot, *.mo
> files are all interim products behind the scenes.  The translated *.rst
> files would NOT be part of the numpy source code, but packaged separately.
> I must admit that I did hope that there would be more interest.  Maybe I
> should have figured out how to put 'maskna' or '1.7' in the subject?
> In defense of there not be much interest is that the people who would
> possibly benefit, aren't reading English mailing lists.

One advantage of getting this done would be that other packages could
follow the same approach.

Just as numpy.testing and numpy's doc standard has spread to related
packages, being able to generate translations might be even more
interesting to downstream packages. There the fraction of end users,
that are not used to working in english anyway, might be larger than
for numpy itself.

The numpy mailing list may be to narrow to catch the attention of
developers with enough interest and expertise in the area.


> Kindest regards,
> Tim
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion

More information about the NumPy-Discussion mailing list