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 #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

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 85.52%. Comparing base (886f15e) to head (15f41ab). :warning: 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              

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

[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]

• 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.