Support language tagging for roles and directives #14245
Description
There is currently no way in Sphinx to specify a piece of text is written in a different natural language. There is no such role like :lang:jp:`日本語` or directive properties like :lang: jp.
In HTML, there is a way to specify some parts of a webpage are written in a different natural language other than the one globally specified in <html lang="en">, like this example from MDN:
<p>This paragraph is English, but the language is not specifically defined.</p>
<p lang="en-GB">This paragraph is defined as British English.</p>
<p lang="fr">Ce paragraphe est défini en français.</p>This is useful when writing documents mixed with multiple languages and is propsed by web standards:
- Easier for screen readers to switch to a proper language, for example, in an English webpage or a textbook that teaches French.
- Help browsers select correct region-specific/language-specific glyphs. Many characters in CJK(Chinese, Japanese, Korean) languages share the same Unicode code points despite having slightly different glyphs.
I have tried a workaround by inserting following rst code at the beginning of my article that defines a new role with class jp and injects JavaScript code to add lang attribute when DOM tree is ready:
.. role:: jp
:class: lang-jp
.. raw:: html
<script>
document.addEventListener("DOMContentLoaded", () => {
document
.querySelectorAll(".lang-jp")
.forEach((n) => n.setAttribute("lang", "jp"));
});
</script>I can then use this role :jp:`音読み` and mix Japanese with other languages in my article. This really feels like a hack because it is not portable and only works in HTML outputs.