Emit translator comments.

This adjusts extract_messages to collect comments.  The return type is
expanded from a String to a structured ExtractedMessage that allows it
to carry an optional `translator_comment` field, which is threaded up
to catalog creation.

i18n-helpers/src/bin/mdbook-xgettext.rs

@@ -43,7 +43,7 @@ fn strip_link(text: &str) -> String {
     without_link
 }
 
-fn add_message(catalog: &mut Catalog, msgid: &str, source: &str) {
+fn add_message(catalog: &mut Catalog, msgid: &str, source: &str, translator_comment: &str) {
     let wrap_options = textwrap::Options::new(76)
         .break_words(false)
         .word_splitter(textwrap::WordSplitter::NoHyphenation);
@@ -54,6 +54,7 @@ fn add_message(catalog: &mut Catalog, msgid: &str, source: &str) {
     let message = Message::build_singular()
         .with_source(sources)
         .with_msgid(String::from(msgid))
+        .with_comments(translator_comment.into())
         .done();
     catalog.append_or_update(message);
 }
@@ -77,14 +78,21 @@ fn create_catalog(ctx: &RenderContext) -> anyhow::Result<Catalog> {
     let summary_path = ctx.config.book.src.join("SUMMARY.md");
     let summary = std::fs::read_to_string(ctx.root.join(&summary_path))
         .with_context(|| anyhow!("Failed to read {}", summary_path.display()))?;
-    for (lineno, msgid) in extract_messages(&summary) {
+    for (lineno, extracted_msg) in extract_messages(&summary) {
+        let msgid = extracted_msg.message;
         let source = format!("{}:{}", summary_path.display(), lineno);
+
         // The summary is mostly links like "[Foo *Bar*](foo-bar.md)".
         // We strip away the link to get "Foo *Bar*". The formatting
         // is stripped away by mdbook when it sends the book to
         // mdbook-gettext -- we keep the formatting here in case the
         // same text is used for the page title.
-        add_message(&mut catalog, &strip_link(&msgid), &source);
+        add_message(
+            &mut catalog,
+            &strip_link(&msgid),
+            &source,
+            &extracted_msg.translator_comment.unwrap_or(String::from("")),
+        );
     }
 
     // Next, we add the chapter contents.
@@ -94,9 +102,15 @@ fn create_catalog(ctx: &RenderContext) -> anyhow::Result<Catalog> {
                 Some(path) => ctx.config.book.src.join(path),
                 None => continue,
             };
-            for (lineno, msgid) in extract_messages(&chapter.content) {
+            for (lineno, extracted) in extract_messages(&chapter.content) {
+                let msgid = extracted.message;
                 let source = format!("{}:{}", path.display(), lineno);
-                add_message(&mut catalog, &msgid, &source);
+                add_message(
+                    &mut catalog,
+                    &msgid,
+                    &source,
+                    &extracted.translator_comment.unwrap_or(String::from("")),
+                );
             }
         }
     }
@@ -281,6 +295,41 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn test_create_catalog_comments() -> anyhow::Result<()> {
+        let (ctx, _tmp) = create_render_context(&[
+            ("book.toml", "[book]"),
+            ("src/SUMMARY.md", "- [The *Foo* Chapter](foo.md)"),
+            (
+                "src/foo.md",
+                "
+<!-- mdbook-xgettext-comment: This is a header. -->
+# How to Foo
+
+<!-- mdbook-xgettext-comment: I am a comment. -->
+The first paragraph about Foo.
+Still the first paragraph.
+",
+            ),
+        ])?;
+
+        let catalog = create_catalog(&ctx)?;
+
+        for msg in catalog.messages() {
+            assert!(!msg.is_translated());
+        }
+
+        assert_eq!(
+            catalog
+                .messages()
+                .map(|msg| msg.comments())
+                .collect::<Vec<&str>>(),
+            &["", "This is a header.", "I am a comment."]
+        );
+
+        Ok(())
+    }
+
     #[test]
     fn test_create_catalog_duplicates() -> anyhow::Result<()> {
         let (ctx, _tmp) = create_render_context(&[