docs: Add translation file generation with Justfile

docs/Justfile

@@ -1,3 +1,5 @@
+export PATH := justfile_directory() + "/utils:" + env("PATH")
+
 _default:
     just --list
 
@@ -5,9 +7,13 @@ _default:
 install_dependencies:
     bash ./utils/install-deps.sh
 
-build_messages_pot:
+_build_messages_pot:
+    #!/usr/bin/bash
+    DEBUG=1 ./utils/pre-build.py -s src -o src.tmp
+    MDBOOK_BOOK__SRC="src.tmp" \
     MDBOOK_OUTPUT='{"xgettext": {}}' \
         mdbook build -d po
+    rm -r src.tmp
 
 # Check that a translation file exists, otherwise exit with 1
 _is_translation LANG:
@@ -17,7 +23,7 @@ _is_translation LANG:
         exit 1; }
 
 # Add a language to translate
-add_translation LANG: build_messages_pot
+add_translation LANG: _build_messages_pot
     msginit -i po/messages.pot -l {{LANG}} -o po/{{LANG}}.po
 
 # Flatten a directory containing multiple mdbook outputs
@@ -36,8 +42,7 @@ _flatten_outputs OUTPUTS_DIR="./book":
     done
 
 # Update a language with a fresh messages.pot
-update_translation LANG: (_is_translation LANG) build_messages_pot
-    mdbook clean
+update_translation LANG: (_is_translation LANG) _build_messages_pot
     msgmerge --update po/{{LANG}}.po po/messages.pot
 
 # Equivalent to 'mdbook build'
@@ -65,5 +70,5 @@ mdbook_serve LANG="":
     fg
 
 # Same as 'mdbook_serve' but for a specific language
-preview_translation LANG: (_is_translation LANG) build_messages_pot
+preview_translation LANG: (_is_translation LANG)
     just mdbook_serve {{LANG}}

docs/utils/pre-build.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+
+__doc__ = """Preprocess markdown files in order to be processed by mdbook-i18n-helpers
+"""
+
+import argparse
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+
+def execute_command(command: Optional[str]) -> str:
+    if not command:
+        return ""
+    try:
+        result = subprocess.run(
+            shlex.split(command),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as err:
+        return f"Error: {err.stderr.strip()}"
+
+
+def debug(*msg) -> None:
+    if os.getenv("DEBUG") == "1":
+        return print("[DEBUG]:", *msg, file=sys.stderr)
+
+
+def exe_wrapper(match: re.Match[str]):
+    return execute_command(match.group(1) or None)
+
+
+def render(content: str):
+    templ = r"<!-- cmdrun (.*)\s?-->\n?"
+    return re.sub(templ, exe_wrapper, content)
+
+
+def main():
+    argparser = argparse.ArgumentParser()
+    argparser.add_argument(
+        "-s",
+        "--src",
+        help="Directory with all markdown files",
+        type=str,
+        required=True,
+    )
+    argparser.add_argument(
+        "-o",
+        "--output",
+        help="Where to store files",
+        required=True,
+    )
+
+    args = argparser.parse_args()
+    # Move files to temporary directory
+    src_md_directory = Path(args.src)
+    _dst_md_directory = Path(args.output)
+    if _dst_md_directory.exists():
+        shutil.rmtree(_dst_md_directory)
+    dst_md_directory = shutil.copytree(src_md_directory, _dst_md_directory)
+
+    files_to_parse = [Path(f) for f in dst_md_directory.glob("**/*.md")]
+
+    for file in files_to_parse:
+        content_to_write: str = render(file.read_text(encoding="utf-8"))
+        with open(file, "w") as out:
+            out.write(content_to_write)
+        debug(f"File '{file.name}' was parsed")
+
+    print(dst_md_directory)
+
+
+if __name__ == "__main__":
+    main()