Translation docstrings with gettext

[Lie Ryan]

On 04/06/10 19:52, sapient wrote:
> Lie Ryan, thank you for your answer!
>> Why would you want to translate docstring? Docstring is meant for
>> developers not users.
> I have mentioned that I want to provide API for existing image-
> processing applicaion in Python.
> In my case "developers" are "users".
> Python provides great possibilities for documenting objects, I want to
> use it for things such context help about API modules, classes,
> methods, and want to do it in several languages.
> 
>> Maintaining a translated docstring is going to be
>> a maintenance hell and will either hampers your application's agility or
>> you will be left with obsolete docstrings in various languages you don't
>> know.
> You are right, there are problems here, but there are advantages too
> (we are talking about API): developers can write documentation in
> thier "cracked" English (like my), but professional translator can
> correct it after with Poedit.

Fair enough.

>> Anyway, my job is to answer questions, not question the economic
>> feasibility of your decision, so try this:
>>
>> #!python
>> __doc__ = _("""testmodule docstring""")
>>
>> class TestClass:
>>     __doc__ = _("""testmodule.TestClass docstring""")
>>
>>     def testClassMethod(self):
>>         __doc__ = _("""testmodule.TestClass.testClassMethod docstring""")
>>         print _("Call TestClass.testClassMethod()")
> Yes, I tried this method, but it does not work with methods and
> functions, this line
>>         __doc__ = _("""testmodule.TestClass.testClassMethod docstring""")
> does nothing (There are not output in help()). 

Ah, my bad; I didn't notice.

> Is it any way to assign
> docstring for function explicity?

Yes there is, you will need to reassign the (translated) __doc__ from
*outside* the function definition, a decorator will provide nice
wrapper. This works:

__doc__ = _("""testmodule docstring""")__doc__ = _("""testmodule
docstring""")

def tdoc(obj):
    obj.__doc__ = _(obj.__doc__)
    return obj

@tdoc
class TestClass:
    """testmodule.TestClass docstring"""
    @tdoc
    def testClassMethod(self):
        """testmodule.TestClass.testClassMethod docstring"""
        print _("Call TestClass.testClassMethod()")

    # the decorator is equivalent to:
    # def testClassMethod(self):
    #     print _("Call TestClass.testClassMethod()")
    # testClassMethod.__doc__ = _(testClassMethod.__doc__)


as I said, you probably will want to use some metaclass magic to
automatically apply tdoc to all classes and methods. If just mandating
that tdoc must decorate everything works for you, then great.

>> If you want to avoid having the explicit assignment to __doc__, you can
>> also try using some metaclass or decorator magic to automatically wraps
>> docstring in a _() call.
> 
> Yes, it will be better to avoid them, is it any existing tool/lib/
> workaround that can do it?
> I am follower of aproved, stable solutions, do not like to reinvent
> the wheel.