Skip code blocks without translatable strings

[mgeisler]

With google/mdbook-i18n-helpers#69 by @dyoo merged, we can make mdbook-xgettext can skip code blocks by prefixing them with <!-- mdbook-xgettext: skip -->.

This allows us to remove a lot of uninteresting lines from the PO files, thus removing churn from the translators.

The suggested approach is to translate strings and comments in the code blocks. So if a code block only contain un-translatable strings such as

println!("foo: {foo}");

then it should be skipped. The heuristic in google/mdbook-i18n-helpers#75 will automatically skip code blocks that don't contain any literal strings or comments — but this is not enough to skip a block with the println! call above.

Mark such blocks with <!-- mdbook-xgettext: skip -->. Also consider rephrasing the strings in code blocks to remove translatable content. Avoid unnecessary comments when we can explain things in the surrounding text instead.

[mgeisler]

@0scvr, thanks for attacking #1327! Could you generate a fresh messages.pot file and scan it for any left-over code blocks which we can exclude? If there are no more problematic cases left, then we can close this one.

[0scvr]

@0scvr, thanks for attacking #1327! Could you generate a fresh messages.pot file and scan it for any left-over code blocks which we can exclude? If there are no more problematic cases left, then we can close this one.

Sure, no problem.

[0scvr]

I've generated a fresh messages.pot file and it seems there are still quite a few code blocks being unnecessarily included in the final translations. Where do you want to go from here @mgeisler ?

Here's the messages.pot file for reference (had to rename it to .txt for upload):
messages_16_10_2023.txt

[mgeisler]

I've generated a fresh messages.pot file and it seems there are still quite a few code blocks being unnecessarily included in the final translations.

Nice, thank you! I see that the file is less than 20k lines now! That's an improvement 😄

Where do you want to go from here @mgeisler ?

I would suggest that we remove all exercise solutions from the translations. At least for now: they take up lots of space and cause work for the translators who are already very busy with the main text.

So I would appreciate it if you add more mdbook-xgettext: skip comments throughout the course. That is a quick but impactful change which will help the translators.

Longer we should implement google/mdbook-i18n-helpers#95 to automatically only extract the comments and literal strings from the code blocks. We should also extend the auto-skip functionality from @dyoo: I had some ideas in google/mdbook-i18n-helpers#75 (comment): in particular, we could say that we skip all code blocks with Rust code.

[0scvr]

I've generated a fresh messages.pot file and it seems there are still quite a few code blocks being unnecessarily included in the final translations.

Nice, thank you! I see that the file is less than 20k lines now! That's an improvement 😄

Where do you want to go from here @mgeisler ?

I would suggest that we remove all exercise solutions from the translations. At least for now: they take up lots of space and cause work for the translators who are already very busy with the main text.

So I would appreciate it if you add more mdbook-xgettext: skip comments throughout the course. That is a quick but impactful change which will help the translators.

Longer we should implement google/mdbook-i18n-helpers#95 to automatically only extract the comments and literal strings from the code blocks. We should also extend the auto-skip functionality from @dyoo: I had some ideas in google/mdbook-i18n-helpers#75 (comment): in particular, we could say that we skip all code blocks with Rust code.

Ok, so just to be clear, for now I should ignore all code blocks or only code blocks who do not have comments and translatable literal strings ?

I agree with what you suggested for a better long term approach though. I'll check it out some more this weekend and see if that's something I could handle.

[mgeisler]

Ok, so just to be clear, for now I should ignore all code blocks or only code blocks who do not have comments and translatable literal strings ?

I would start by skipping all exercise solutions, even if they have translatable strings. They are huge and we should not burden the translators with them. I think we can remove 1-2k lines lines with that.

Afterwards, we can start ignoring other code blocks which only have "uninteresting" string such as println!("a: {a:?}") lines.

I did some of that in #1258: I also changed code blocks to remove unnecessary comments and text. This is harder and it is a a tradeoff: I think it's awesome that the comments here are translated into Simplified Chinese! I think that's very useful to people learning Rust — but we should not bother translating the large enum size examples.

I agree with what you suggested for a better long term approach though. I'll check it out some more this weekend and see if that's something I could handle.

That would be cool! I honestly think that google/mdbook-i18n-helpers#95 would be a lot of fun 😄

[0scvr]

I would start by skipping all exercise solutions, even if they have translatable strings. They are huge and we should not burden the translators with them. I think we can remove 1-2k lines lines with that.

Afterwards, we can start ignoring other code blocks which only have "uninteresting" string such as println!("a: {a:?}") lines.

I did some of that in #1258: I also changed code blocks to remove unnecessary comments and text. This is harder and it is a a tradeoff: I think it's awesome that the comments here are translated into Simplified Chinese! I think that's very useful to people learning Rust — but we should not bother translating the large enum size examples.

Sounds good. I'll take a look at #1258 and start removing some code blocks later today.

[mgeisler]

This has been made mostly obsolete by google/mdbook-i18n-helpers#109 and I think we should close it now.