make docfield translatable

#96 Merged at 2431020
  1. Nozomu Kaneko

sphinx.util.docfields generates untranslatable nodes. Unfortunately, it's hard to fix it with only existing nodes (e.g. paragraph). So I introduced a new node class called translatable in sphinx.addnodes.

Comments (11)

  1. Robert Lehmann

    Sorry I'm so late for this pull request. I'd strongly oppose introducing a new doctree node; those should be used sparingly IMO because, as you can see in the patch, every single builder needs to care about them. It also seems weird to have a node called translatable, and then used only for a very small subset of actually translatable nodes. Is there any less intrusive way to fix this?

    1. Nozomu Kaneko author

      Thank you for your comment. I understand what you mean. Actually, I don't like such an intrusive way, too.

      There are two reasons why I introduced the new node:

      1. I didn't find any suitable node, so I realized that some sort of new node should be introduced anyway.
      2. There are similar issues in other various nodes (both sphinx's and docutils'). A general solution is more preferable.

      I'll investigate another less intrusive approach a bit more.

  2. Robert Lehmann

    The core reason why docfields are not picked up by the translation mechanism is because they do not have a source attribute (let alone a rawsource), and it is hard to assign one.

    The seemingly simple parameter reference (inside a class)

    :param arg1: foo *bar* baz

    …generates a halfway-translatable, halfway-untranslatable doctree:

        <!-- everything from here needs to be translated -->

    (I know you have already diagnosed all of this, I'm just typing it out for posterity.)

    I'm honestly wondering why it doesn't use field list nodes in the first place, and if perhaps that's something we should aim for in future releases. I performed a cursory search through Docutils' builtin nodes and did not find any satisfactory doctree element we could (ab)use.

  3. Georg Brandl repo owner

    I agree that introducing a new node is not what we want. If another solution can be found, I'm fine with it; the current translation into (existing) nodes is not set in stone. It probably is that way because that was the easiest way I could find at the time.

  4. Nozomu Kaneko author

    I updated the pull request. Compared with the previous one, it contains:

    • remove translatable node
    • add a transformer to handle nested paragraph nodes

    How do you all think about it? I feel that it is a little bit ad-hoc but less intrusive way.

  5. Jon Waltman

    Instead of introducing a new node, what about using nodes.inline with a "translatable" class which could be checked for in extract_messages? This could also be used in other cases where you want to mark something as being translatable.

    Asides from generating spans with a "translatable" class, I don't think it would otherwise affect the html output.

  6. Nozomu Kaneko author

    Updated PR to use nodes.inline with a "translatable" attribute.

    I ended up keeping a transformer which eliminates "translatable" inline nodes since extra spans break some existing tests.