MyST-Parser
MyST-Parser copied to clipboard
[RFC] Rebuild link labels for Sphinx i18n support
When processing translations in Sphinx, after Sphinx's i8n transform replaces parts of a document with a translation, a document is processed a message at a time through the MyST-parser. For references using link labels, these may not be to the parse for the specific messages that need them and links may be left unbuilt after processing a document.
To prevent issues when using translations, cache any detected label references when processing a given document. And when individual messages are parsed after translation, rebuild any label references and append them to the message first. This will ensure references will be resolved/built as expected.
RFC
Limited testing has been done. This appears to resolve my use case; however, I cannot say I have a complete understanding of MyST with Sphinx to know if the changes are right. If this (with maybe tweaks) works, great; if a completely different approach is needed, that's fine -- hopefully this example/workaround can provide hints to a better implementation.
About
Noticed after converting a project from using reStructuredText to Markdown, any references built using labels would not be properly rendered when inside a part of a document that had a translation. For example, the default English document:
Would result in the following using stock MyST-parser with Sphinx:
And after applying the changes in this pull request, translated messages would work as expected:
The following repository can be used to demonstrate the issue:
- https://github.com/jdknight/sphinx-i8n-myst-example
Thanks for submitting your first pull request! You are awesome! :hugs:
If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.
Welcome to the EBP community! :tada:
Thanks I'll have a look and think about it.
Obviously it would be good to implement a test that demonstrates the current failure
I tried this branch to check if it would solve my problem #844, but I still have the same amount of warnings.
This branch seems to be more about #690