Question

我想为自己创建一个新模块，但我也想让一些同事能够使用它。我开始用英语编写我的文档字符串，但后来我意识到，对于那些不太了解这种语言的人来说，它会使模块变得无用。

我的第一个想法是输入英语，并在同一文档字符串中输入西班牙语。但这似乎不对，如果我想让一些俄罗斯朋友也使用它呢？如果我的朋友在世界各地都有朋友没有任何共同语言来阅读文档会怎样？

用多种语言编写和阅读文档字符串的最简单方法是什么？

Answer 1

无法将docstring转换为多种语言，但您可以通过Sphinx工具创建文档并翻译文档。

Sphinx本身支持生成的文档的基于gettext的翻译，请查看Sphinx Internationalization Guide。

Answer 2

我有同样的问题;排序：cmd模块使用docstrings向最终用户打印帮助，我真的需要一种方法来使用多种语言的文档字符串。我是这样做的：

使用gettext模块查看此awesome tutorial。这使您可以翻译任何Python应用程序。我这样用它：

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

现在，无论何时想要将文档字符串国际化，请遵循以下模式：

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.''')

现在是时候阅读that tutorial我之前提到的：在您的代码上致电pygettext，使用poedit创建翻译，并享受乐趣。

Adiós，paisanos。

Answer 3

要改善Mario的答案，您可以将文档字符串放在装饰器中，使其位于函数的开头。


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):
        ...

仍然不理想，但是比使文档字符串视而不见/头脑混乱在底部更好。

Answer 4

关于我能想到的唯一实用的解决方案 - 它很难看 - 是在文档字符串中放置一种语言。例如：

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

如何在python中为多种语言编写docstring

4 个答案: