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? Also the content of the directive should be exposed to translation and translated. 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]