Add book metadata to gettext extraction

[cnaples79]

Summary

• include book title and description from book.toml in the xgettext catalog
• teach tests to expect the metadata entries and document how to localize them

Rationale

• translators requested that book-level metadata be translated alongside chapters (Fixes Add book title and description to translation #269)

Changes

• add book metadata extraction to mdbook-xgettext and cover it with unit tests
• update usage docs with instructions for overriding localized metadata

Fixes #269

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.52%. Comparing base (886f15e) to head (15f41ab).
⚠️ Report is 33 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #283      +/-   ##
==========================================
+ Coverage   84.74%   85.52%   +0.77%     
==========================================
  Files          15       17       +2     
  Lines        3377     3379       +2     
  Branches     3377     3379       +2     
==========================================
+ Hits         2862     2890      +28     
+ Misses        413      387      -26     
  Partials      102      102              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mgeisler]

If translating the title and description in the .po file doesn't actually do anything, then we should not add this. Or we should rework it in some way to make it have the desired effect 😄

[mgeisler]

Oh, this makes me think that translating the string (in the .po file) doesn't actually have any effect?

[cnaples79]

@mgeisler I'm re-working the Implementation on this.

[cnaples79]

Thanks for the detailed feedback. I've updated the changes so the translated metadata is actually used during the build:

• the title/description strings now go into the gettext catalog without the hard-coded translator comments you flagged,
• the gettext preprocessor translates those strings and injects a tiny script that updates the HTML title, menu chrome, and meta description when a translation is present,
• USAGE docs no longer mention manual env overrides, and
• unit tests cover the metadata injection so we know it stays wired up.

running 145 tests

test result: ok. 145 passed; 0 failed; 0 ignored; 0 measured; 0 filtered

Let me know what you think.

[mgeisler]

I'm sorry, but I don't think this is a good approach: injecting JavaScript into every Markdown file (if I read it correctly) is very invasive and surprising.

People will have questions and I don't have answers for them 😄

Basically, if this is not supported in upstream mdbook, then we cannot support it here either.

[mgeisler]

• the gettext preprocessor translates those strings and injects a tiny script that updates the HTML title, menu chrome, and meta description when a translation is present,
• USAGE docs no longer mention manual env overrides, and

Okay, so I think I understand now that this isn't supported by mdbook? I think the problem lies in Preprocessor::run:

    /// Run this `Preprocessor`, allowing it to update the book before it is
    /// given to a renderer.
    fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book>;

Basically, the signature doesn't allow us to modify the PreprocessorContext, only the Book. So I believe a preprocessor (which is what our mdbook-gettext binary is) cannot modify the metadata, it can only modify the book content.

If that is correct, then a first step would be to open an issue about this in the upstream mdbook repository.

Now that I have a fuller picture, I'm also okay with your first approach: extract the metadata and include instructions in a README for how to use it. With the upstream issue, the README should link back to mdbook and explain the limitation.