Add support for translating HTML blocks

[shinmili]

The current implementation of mdbook-xgettext extracts (inline) raw HTML tags as translatable, but skips HTML blocks. So the extracted .po file has msgid for this img:

...

<img alt="Two tables: the first table contains the representation of s1 on the
stack, consisting of its length (5), capacity (5), and a pointer to the first
value in the second table. The second table contains the representation of the
string data on the heap, byte by byte." src="img/trpl04-01.svg" class="center"
style="width: 50%;" />

...

but not for this img:

...

<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-01.png" class="center" />

...

I want the latter one to be translatable too, especially for alt texts. Why does it skip HTML blocks?

[michael-kerscher]

As I authored 2168b9c some time ago this sounded familiar, so these are my 2 cents.

To cmark these two definitions are not the same: AST of your examples in dingus

The first one is a <html_inline> the second one is a <html_block>
I suppose if you create a new line in the second example (e.g. after src), you might achieve what you intend - can you verify?

This will not work (<html_block>):

<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-01.png" class="center" />

This should work (<html_inline>):

<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`"
src="img/trpl14-01.png" class="center" />

[shinmili]

@michael-kerscher Thank you, I understand the difference between <html_block> and <html_inline>, and yes, I can confirm the latter one does generate the expected msgid. However, the snippets in the opening comment are just what I actually came across.

I still have the same question, in general: Why are HTML blocks skipped? Unless there is a good reason for that, I would like to suggest extracting them as translatable by default, because they can contain translatable contents.

I could think of some other cases where skipping HTML blocks would lead to a missing translation problem:

• What if I happen to choose to wrap the <img> in <p>...</p> instead, in order to make it inline? This generates a final HTML output basically the same as the <img> with a newline inside, but is still <html_block> and would be skipped.
• What if somebody refuses any non-CommonMark extensions and sticks to use <table>? It is type 6, so following contents until the next blank line are all wrapped in <html_block> and would be skipped. Unlike <img> (which is type 7) adding a newline doesn't work in this case.

[michael-kerscher]

@mgeisler any idea?

[dalance]

I found a related issue. "The Rust Programming Language" contains the following HTML blocks,
and the caption should be translated.

<Listing number="1-2" file-name="Cargo.toml" caption="Contents of *Cargo.toml* generated by `cargo new`">
...
</Listing>

Instead of whole HTML block, extracting strings (e.g. "1-2", "Cargo.toml" and "Contents...") in the block may be an alternative.

Refer: rust-lang-translations/translations#6

[mgeisler]

I still have the same question, in general: Why are HTML blocks skipped? Unless there is a good reason for that, I would like to suggest extracting them as translatable by default, because they can contain translatable contents.

Yes, I agree! I'm not actually sure if there were any good reason to skip them — except that we don't use them in Comprehensive Rust right now.

But I agree with you: if someone likes to add HTML to their Markdown, then we should not prevent this from being translated.

There could be multiple levels of support for HTML blocks:

1. Simply put them verbatim in the translation file.
2. Put attributes and text between elements into the translation file.

The approaches match how we approached the Markdown itself: the version version of mdbook-i18n-helpers would simply split the input on \n\n and that was it. The current version is very much aware of the Markdown AST and will extract the text more carefully.

I'm suggesting a similar approach for HTML: start with a simple approach and then perhaps make it more fine-grained down the road.

This could even be a configuration setting: users could specify that they want to extract text from alt and title attributes, but not for height and width.