Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Rebuild link labels for Sphinx i18n support #800

Open
wants to merge 3 commits into
base: master
Choose a base branch
from

Conversation

jdknight
Copy link

@jdknight jdknight commented Aug 6, 2023

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:

image

Would result in the following using stock MyST-parser with Sphinx:

image

And after applying the changes in this pull request, translated messages would work as expected:

image

The following repository can be used to demonstrate the issue:

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.

Signed-off-by: James Knight <james.d.knight@live.com>
@welcome
Copy link

welcome bot commented Aug 6, 2023

Thanks for submitting your first pull request! You are awesome! 🤗

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! 🎉

@chrisjsewell
Copy link
Member

Thanks I'll have a look and think about it.

Obviously it would be good to implement a test that demonstrates the current failure

@n-peugnet
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants