How to docstring in python for multiple languages

Question

I want to create a new module for myself but I also want some colleagues to be able to use it. I started writing my docstrings in English but then I realized that it will make the module useless for some of them who are not good understanding this language.

My first idea was to type both English and, on the same docstring, Spanish. But this doesn't seem right, what if I want some Russian friends to use it too? What if I've got friends who have friends all over the world who don't have any common language to read docs in?

What's the easiest way to write and then read docstrings in multiple languages?

There is no way to make docstring translated to multiple languages but you can create documentation via sphinx and translate the docs. — Andrew Svetlov, Dec 02 '14 at 23:22
@AndrewSvetlov, yes, please elaborate and add as an answer, seems a good solution. — Andre Polykanine, Dec 03 '14 at 15:19

score 5 · Answer 1 · answered Aug 22 '16 at 14:32

I had the same issue; sort of: The cmd module uses docstrings to print help to the end user and I really needed a way to have docstrings in multiple languages. Here's how I did it:

Have a look at this awesome tutorial for using gettext module. This enables you to translate any Python app. I use it like this:

import gettext
try:
    lang = gettext.translation('myawesomeapp', localedir='locale')
    lang.install()
except FileNotFoundError:
    _ = lambda x: x

And now, whenever you want to internationalize a docstring, follow this pattern:

class MyAwesomeClass:
    def incredible_method(with_fantastic_args):
        # Some marvellous code

    incredible_method.__doc__ = _('''\
Place here a fabulous docstrig for your incredible method.
This will be translated by the gettext module at runtime.''')

Now is the time to read that tutorial I mentioned earlier: call pygettext on your code, use poedit to create translations, and have fun.

Adiós, paisanos.

score 4 · Accepted Answer · edited Aug 19 '18 at 13:40

4

There is no way to make docstring translated to multiple languages but you can create documentation via Sphinx tool and translate the docs.

Sphinx itself supports gettext-based translations for generated docs, take a look on Sphinx Internationalization Guide.

edited Aug 19 '18 at 13:40

astrojuanlu

6,744
8
45
105

answered Dec 03 '14 at 20:29

Andrew Svetlov

16,730
8
66
69

Marked as best answer because Sphinx is a good way to go. Also found [this alternative](http://stackoverflow.com/questions/2258696/more-than-1-docstrings-for-a-single-module-function-etc?rq=1), but it doesn't escalate well for many languages. – Rubén Cabrera Dec 07 '14 at 11:38
'There is no way to make docstring translated to multiple languages' this is wrong, below answer by Matthias gives example on how to do it. – BrainDead Aug 15 '21 at 11:17
Well, it can work but looks too tricky for my eyes. Plus doesn't work well with Static Analysis Tools. The simpler is better I believe. – Andrew Svetlov Sep 02 '21 at 11:33

score 4 · Answer 3 · answered Aug 05 '20 at 16:48

To improve on the answer by Mario, you can put the docstrings in a decorator so they'll be at the start of the function.


def doc(docstring):
    def decorate(fn):
        fn.__doc__ = docstring
        return fn
    return decorate

class MyAwesomeClass:

    @doc(_(
    """My awesome documentation for an incredible method.
 
       It's really awesome, isn't it?
       """))
    def incredible_method(with_fantastic_args):
        ...

Still not ideal, but way better than having the docstring out-of-sight/out-of-mind somewhere at the bottom.

Excellent idea, the accepted answer 'There is no way to make docstring translated to multiple languages' is misleading and your example idea is just what I need. — BrainDead, Aug 15 '21 at 11:20

score -3 · Answer 4 · answered Dec 03 '14 at 01:09

-3

About the only practical solution I can think of - and it's ugly - is to place one language after another in the docstring. For example:

def findChocolate(variety):
    '''Locate chocolate - Encuentra la choloate - nuqDaq yuch Dapol '''
    ...

answered Dec 03 '14 at 01:09

Steve

726
4
10

1

This is really ugly since not really parsable and not "GetText-able" :( – Andre Polykanine Dec 03 '14 at 15:17

How to docstring in python for multiple languages

4 Answers4