Possibility for internationalized sphinx docs?

Development matplotlib-devel
1

Hello all,

Given some recent – ahem – difficulties with matplotlib users where English is not their native language, it has dawned on me that maybe we ought to consider making available translated versions of our documentation. I have absolutely no experience with such efforts, but I did see that Sphinx does support internationalization:

http://sphinx.pocoo.org/latest/intl.html

and I do believe we have some bilingual developers on this list (or at least are active on the users list). While I don’t think it would be possible to translate the API docs effectively, at the very least we should be able to provide translations of other parts.

What does everyone think? Could someone who has done internationalization (particularly using sphinx) comment? What languages would we like the docs to be in?

Ben Root

2

If anyone is looking for me, I'll be cowering under my desk.

···

On Tue, Feb 22, 2011 at 2:45 PM, Benjamin Root <ben.root@...553...> wrote:

Hello all,

Given some recent -- ahem -- difficulties with matplotlib users where
English is not their native language, it has dawned on me that maybe we
ought to consider making available translated versions of our
documentation. I have absolutely no experience with such efforts, but I did
see that Sphinx does support internationalization:

http://sphinx.pocoo.org/latest/intl.html

and I do believe we have some bilingual developers on this list (or at least
are active on the users list). While I don't think it would be possible to
translate the API docs effectively, at the very least we should be able to
provide translations of other parts.

What does everyone think? Could someone who has done internationalization
(particularly using sphinx) comment? What languages would we like the docs
to be in?

3

Hello all,

Given some recent -- ahem -- difficulties with matplotlib users where
English is not their native language, it has dawned on me that maybe we
ought to consider making available translated versions of our
documentation. I have absolutely no experience with such efforts, but I
did see that Sphinx does support internationalization:

http://sphinx.pocoo.org/latest/intl.html

and I do believe we have some bilingual developers on this list (or at
least are active on the users list). While I don't think it would be
possible to translate the API docs effectively, at the very least we
should be able to provide translations of other parts.

I think this is premature. My sense is that there are other aspects of the docs and code that should be cleaned up first, and that having translations of the docs will actually make this more difficult--there will be more pieces of the system to try to keep up to date.

Eric

···

On 02/22/2011 09:45 AM, Benjamin Root wrote:

What does everyone think? Could someone who has done
internationalization (particularly using sphinx) comment? What
languages would we like the docs to be in?

Ben Root

------------------------------------------------------------------------------
Free Software Download: Index, Search& Analyze Logs and other IT data in
Real-Time with Splunk. Collect, index and harness all the fast moving IT data
generated by your applications, servers and devices whether physical, virtual
or in the cloud. Deliver compliance at lower cost and gain new business
insights. http://p.sf.net/sfu/splunk-dev2dev

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

4

> Hello all,
>
> Given some recent -- ahem -- difficulties with matplotlib users where
> English is not their native language, it has dawned on me that maybe we
> ought to consider making available translated versions of our
> documentation. I have absolutely no experience with such efforts, but I did
> see that Sphinx does support internationalization:
>
> http://sphinx.pocoo.org/latest/intl.html

Hi Ben,

a soft on this -1 from me. At this time, I feel that matplotlib has neither
the user base need, nor the developer / i18n expert bandwidth to make this
happen. As a point of reference, even the Python docs aren't
internationalized, at the moment.

>
> and I do believe we have some bilingual developers on this list (or at least
> are active on the users list). While I don't think it would be possible to
> translate the API docs effectively, at the very least we should be able to
> provide translations of other parts.

which parts? Tutorials? It seems like these sorts of things
self-organize around individuals who write about the software in
their language of choice. Folks searching the web for something
like "python publication quality graphics" in Esperanto or
Klingon will find one another, if there are enough of them, and
if there aren't enough of them, we'd have a very hard time
helping them.

>
> What does everyone think? Could someone who has done internationalization
> (particularly using sphinx) comment? What languages would we like the docs
> to be in?

I think the fact that there isn't a language that automatically
pops into our heads suggests to me that we could expand a lot of
effort to do this without users that actually need it.

Darren Dale, on 2011-02-22 14:52, wrote:

If anyone is looking for me, I'll be cowering under my desk.

English being lingua franca :wink: is fairly typical in the software
world, but that doesn't mean we should feel free to sprinkle
idioms and confusing cultural references everywhere. I'm guilty
of both of these, as I sometimes try to add "color" to my
comments, which might produce a chuckle for the folks who
understood, but be a source of unneeded confusion for others.

So may I propose an alternative, which I've seen in somewhere
else, but completely blanking on where: add to our FAQ (or some
similar place) comment requesting feedback along these lines:

  All of the documentation is in English: is there a
  <insert-language> translation of matplotlib documentation?
  
  We strive to make matplotlib accessible to everyone, but lack the
  resource to translate and maintain the documentation in several
  languages. Please help us identify and reword confusing portions
  of the documentation (in particular, idiomatic or otherwise
  untranslatable usage of English in docstrings is considered a
  bug which you should report).

best,

···

On Tue, Feb 22, 2011 at 2:45 PM, Benjamin Root <ben.root@...553...> wrote:

--
Paul Ivanov
314 address only used for lists, off-list direct email at:
http://pirsquared.org | GPG/PGP key id: 0x0F3E28F7

5

I think working on adding new features into mpl and making sure that its a bug-free library are better investments instead of spending time on providing translated documents. Google translate gives a funny but still useful translation in my native language :slight_smile:

Anyways, is there any programming language out or plans for Python that provides syntax for non-English languages?

···

On Tue, Feb 22, 2011 at 12:45 PM, Benjamin Root <ben.root@…553…> wrote:

Hello all,

Given some recent – ahem – difficulties with matplotlib users where English is not their native language, it has dawned on me that maybe we ought to consider making available translated versions of our documentation. I have absolutely no experience with such efforts, but I did see that Sphinx does support internationalization:

http://sphinx.pocoo.org/latest/intl.html

and I do believe we have some bilingual developers on this list (or at least are active on the users list). While I don’t think it would be possible to translate the API docs effectively, at the very least we should be able to provide translations of other parts.

What does everyone think? Could someone who has done internationalization (particularly using sphinx) comment? What languages would we like the docs to be in?

Ben Root

–
Gökhan

6

Hello all,

Given some recent – ahem – difficulties with matplotlib users where English is not their native language, it has dawned on me that maybe we ought to consider making available translated versions of our documentation. I have absolutely no experience with such efforts, but I did see that Sphinx does support internationalization:

http://sphinx.pocoo.org/latest/intl.html

and I do believe we have some bilingual developers on this list (or at least are active on the users list). While I don’t think it would be possible to translate the API docs effectively, at the very least we should be able to provide translations of other parts.

What does everyone think? Could someone who has done internationalization (particularly using sphinx) comment? What languages would we like the docs to be in?

Ben Root

I think Eric had the best point against internationalization:

I think this is premature. My sense is that there are other aspects of

the docs and code that should be cleaned up first, and that having

translations of the docs will actually make this more difficult–there

will be more pieces of the system to try to keep up to date

I definitely do agree with Paul’s point

English being lingua franca :wink: is fairly typical in the software

world, but that doesn’t mean we should feel free to sprinkle

idioms and confusing cultural references everywhere. I’m guilty

of both of these, as I sometimes try to add “color” to my

comments, which might produce a chuckle for the folks who

understood, but be a source of unneeded confusion for others.
I guess I was thinking more along the lines of enabling translation contributions from users as opposed to devoting core development resources to translation. In other words, does it take more than just enabling some options and modifying the doc directory tree to then allow anybody to provide a translated version of a page?

I think working on adding new features into mpl and making sure that its a bug-free library are better investments instead of spending time on providing translated documents. Google translate gives a funny but still useful translation in my native language :slight_smile:

Anyways, is there any programming language out or plans for Python that provides syntax for non-English languages?

Doesn’t Perl5 let you completely restructure its syntax? And bash does have me typing “fi” everywhere…

Ben Root

···

On Tue, Feb 22, 2011 at 3:27 PM, Gökhan Sever <gokhansever@…149…> wrote:

On Tue, Feb 22, 2011 at 12:45 PM, Benjamin Root <ben.root@…553…> wrote:

7

I was thinking to use a variable name of “değişken” instead of “variable”. Can Perl5 allow this? Isn’t that “fi” just for closing match to the “if” in bash?

···

On Tue, Feb 22, 2011 at 3:00 PM, Benjamin Root <ben.root@…553…> wrote:

Doesn’t Perl5 let you completely restructure its syntax? And bash does have me typing “fi” everywhere…

Ben Root

–
Gökhan

8

I see we need an international symbol for sarcasm. Any suggestions?

Ben Root

···

On Tuesday, February 22, 2011, Gökhan Sever <gokhansever@...149...> wrote:

On Tue, Feb 22, 2011 at 3:00 PM, Benjamin Root <ben.root@...553...> wrote:

Doesn't Perl5 let you completely restructure its syntax? And bash does have me typing "fi" everywhere...

Ben Root

I was thinking to use a variable name of "değişken" instead of "variable". Can Perl5 allow this? Isn't that "fi" just for closing match to the "if" in bash?

--
Gökhan