Guidance for custom directive improvement for internationalization

[m-aciek]

Hi, in CPython repo there's a custom directive, availability. It now exposes one string for translation, Availability, which when translated, breaks the rendering.

class Availability(SphinxDirective):
    def run(self) -> list[nodes.container]:
        title = "Availability"
        refnode = addnodes.pending_xref(
            title,
            nodes.inline(title, title, classes=["xref", "std", "std-ref"]),
            refdoc=self.env.docname,
            refdomain="std",
            refexplicit=True,
            reftarget="availability",
            reftype="ref",
            refwarn=True,
        )
        sep = nodes.Text(": ")
        parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno)
        pnode = nodes.paragraph(title, "", refnode, sep, *parsed, *msgs)
        self.set_source_info(pnode)
        cnode = nodes.container("", pnode, classes=["availability"])
        self.set_source_info(cnode)
        if self.content:
            self.state.nested_parse(self.content, self.content_offset, cnode)
        self.parse_platforms()

        return [cnode]

It's previous version was exposing whole sentence with a reference, like

:ref:Availability <availability>: not WASI, not Android.

It's more prone for translators errors.

Ideally Availability could have been translated, but without breaking the reference. Also would it be possible to expose not {platform} part for translation? Could you please share some guidance on how to improve it? The tutorial article doesn't give hints for internationalisation handling: https://www.sphinx-doc.org/en/master/development/tutorials/extending_syntax.html.

Related: python/cpython#126609