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

[m-aciek]

• fix gh-126609: Allow translating the availability directive python/cpython#129549
• not {platform} gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive python/cpython#129597

[AA-Turner]

You may be interested in extract_messages(), which is where the translatable content is found:

sphinx/sphinx/util/nodes.py

Lines 287 to 313 in 50fb4a9

	def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
	"""Extract translatable messages from a document tree."""
	for node in doctree.findall(is_translatable):
	if isinstance(node, addnodes.translatable):
	for msg in node.extract_original_messages():
	yield node, msg # type: ignore[misc]
	continue
	if isinstance(node, LITERAL_TYPE_NODES):
	msg = node.rawsource
	if not msg:
	msg = node.astext()
	elif isinstance(node, nodes.image):
	if node.get('alt'):
	yield node, node['alt']
	if node.get('translatable'):
	image_uri = node.get('original_uri', node['uri'])
	msg = f'.. image:: {image_uri}'
	else:
	msg = ''
	elif isinstance(node, nodes.meta):
	msg = node['content']
	else:
	msg = node.rawsource.replace('\n', ' ').strip() # type: ignore[attr-defined]
	# XXX nodes rendering empty are likely a bug in sphinx.addnodes
	if msg:
	yield node, msg # type: ignore[misc]