Update to handle shared content. (#35)

Author: kattni

.gitignore

@@ -2,6 +2,9 @@
 _build
 comment.md
 
+# uv
+uv.lock
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

docs/locales/de/translations.po

@@ -9,7 +9,7 @@ msgstr ""
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Translate Toolkit 3.16.0\n"
+"X-Generator: Translate Toolkit 3.16.1\n"
 
 #: docs/en/SUMMARY.md:1
 #: docs/en/section_one/index.md:1

docs/locales/fr/translations.po

@@ -9,7 +9,7 @@ msgstr ""
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Translate Toolkit 3.16.0\n"
+"X-Generator: Translate Toolkit 3.16.1\n"
 
 #: docs/en/SUMMARY.md:1
 #: docs/en/section_one/index.md:1

pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
     "python-Levenshtein==0.27.1",
     "PyYAML==6.0.2",
     "polib==1.2.0",
-    "translate-toolkit @ git+https://github.com/kattni/translate@onefile-timestamp",
+    "translate-toolkit==3.16.1",
 ]
 
 [dependency-groups]

src/beeware_docs_tools/build_md_translations.py

@@ -109,7 +109,7 @@ def main():
         temp_md_path = Path(temp_md_directory)
 
         # If source code directory or directories provided, symlink to the
-        # temp directory so it is available relative to the build.
+        # temp directory, so it is available relative to the build.
         if args.source_code:
             for source in args.source_code:
                 # If source includes subdirectories, the parent directory
@@ -131,7 +131,7 @@ def main():
 
             # Load the config.yml file, add the version_number to extra,
             # add the base_path to Snippets, and dump the updated copy to
-            # the temp directory so it is available relative to the build.
+            # the temp directory, so it is available relative to the build.
             with (PROJECT_PATH / "docs/config.yml").open() as f:
                 config_file = yaml.load(f, Loader=yaml.SafeLoader)
 

src/beeware_docs_tools/build_po_translations.py

@@ -23,6 +23,7 @@
 def parse_args() -> Namespace:
     parser = ArgumentParser()
     parser.add_argument("language_code", nargs="*")
+    parser.add_argument("-d", "--docs-directory", type=Path, default="docs")
     args = parser.parse_args()
 
     for language in args.language_code:
@@ -35,66 +36,67 @@ def parse_args() -> Namespace:
 
 
 def pot_to_po(
-    docs_path: Path,
+    docs: Path,
     language: str,
     output_path: Path,
 ) -> None:
     """
     Run `pot2po` with the provided directories.
 
-    :param docs_path: The directory fragment, relative to the project root,
-        containing the `locales` directory.
+    :param root_path: The root directory of the documentation content.
+    :param docs: The directory fragment, relative to the root path, containing
+        the `locales` directory.
     :param language: The language code to convert.
     :param output_path: The root of the output folder where the updated PO file
         will be written.
     """
-    (output_path / docs_path / language).mkdir(parents=True)
+    (output_path / docs / language).mkdir(parents=True)
     subprocess.run(
         [
             "pot2po",
-            f"--template={docs_path / f'locales/{language}/translations.po'}",
-            f"--input={docs_path / 'locales/template/translations.pot'}",
-            f"--output={output_path / docs_path / language}",
+            f"--template={Path.cwd() / docs / f'locales/{language}/translations.po'}",
+            f"--input={Path.cwd() / docs / 'locales/template/translations.pot'}",
+            f"--output={output_path / docs / language}",
         ],
         check=True,
     )
 
 
-def generate_po_files(docs_path: Path) -> None:
+def generate_po_files(docs: Path) -> None:
     """
     Generate PO files from PO template (POT) files.
 
-    :param docs_path: The directory fragment, relative to the project root,
-        containing the `locales` directory.
+    :param root_path: The root directory of the documentation content.
+    :param docs: The directory fragment, relative to the root path, containing
+        the `locales` translation files directories.
     """
     args = parse_args()
 
     with TemporaryDirectory() as temp_dir:
         temp_path = Path(temp_dir)
 
         for language in args.language_code:
-            print(f"Processing {language} content from {docs_path}")
+            print(f"Processing {language} content from {docs}")
 
             # Generates PO files from POT files into a temporary destination
             # directory.
             pot_to_po(
-                docs_path=docs_path,
+                docs=docs,
                 language=language,
                 output_path=temp_path,
             )
 
             # Copies the updated PO file to the `docs` directory.
             shutil.copyfile(
-                (temp_dir / docs_path / language / "translations.po"),
-                (docs_path / f"locales/{language}/translations.po"),
+                (temp_path / docs / language / "translations.po"),
+                (Path.cwd() / docs / f"locales/{language}/translations.po"),
             )
 
 
 def main():
-    # Generate primary content PO files
-    generate_po_files(Path("docs"))
-    # Generate shared content PO files
-    generate_po_files(Path("src/beeware_docs_tools/shared_content"))
+    args = parse_args()
+    # Generate PO files
+    generate_po_files(args.docs_directory)
 
 
 if __name__ == "__main__":

src/beeware_docs_tools/build_pot_translations.py

@@ -1,4 +1,5 @@
 import subprocess
+from argparse import ArgumentParser, Namespace
 from pathlib import Path
 from tempfile import TemporaryDirectory
 
@@ -18,7 +19,15 @@
 # translated site in a given language.
 
 
-def markdown_to_pot(docs_path: Path, working_path: Path) -> None:
+def parse_args() -> Namespace:
+    parser = ArgumentParser()
+    parser.add_argument("-d", "--docs-directory", type=Path, default="docs")
+    args = parser.parse_args()
+
+    return args
+
+
+def markdown_to_pot(docs: Path, working_path: Path) -> None:
     """
     Run `md2po` with provided input and output directories, with `--pot` flag to
     generate PO template (POT) files.
@@ -30,21 +39,20 @@ def markdown_to_pot(docs_path: Path, working_path: Path) -> None:
     * `--timestamp` ensures that new files are only generated when there is new
       content.
 
-    :param docs_path: A directory fragment, relative to the project root,
-        containing the `en` Markdown content and `locales` translation files
-        directories.
+    :param docs: The directory fragment, relative to the root path, containing
+        the `en` Markdown content and `locales` translation files directories.
     :param working_path: The directory considered `/` for the input file call.
         This ensures that the location strings are accurate in the POT and PO
         files.
     """
     # Ensure the output directory exists
-    output_path = Path.cwd() / docs_path / "locales/template"
+    output_path = Path.cwd() / docs / "locales/template"
     output_path.mkdir(parents=True, exist_ok=True)
 
     subprocess.run(
         [
             "md2po",
-            f"--input={docs_path / 'en'}",
+            f"--input={docs / 'en'}",
             f"--output={output_path / 'translations.pot'}",
             "--pot",
             "--timestamp",
@@ -56,40 +64,39 @@ def markdown_to_pot(docs_path: Path, working_path: Path) -> None:
     )
 
 
-def generate_pot_files(docs_path: Path) -> None:
+def generate_pot_files(docs: Path) -> None:
     """
     Generate the PO template (POT) files for the content in the provided
     directory.
 
-    :param docs_path: A directory fragment, relative to the project root,
-        containing the `en` Markdown content and `locales` translation files
-        directories. This will become the msg* string location prefix in the
-        generated POT files.
+    :param docs: The directory fragment, relative to the root path, containing
+        the `en` Markdown content and `locales` translation files directories.
+        This will become the msg* string location prefix in the generated POT
+        files.
     """
     with TemporaryDirectory() as temp_working_directory:
         temp_working_path = Path(temp_working_directory)
 
-        (temp_working_path / docs_path).parent.mkdir(parents=True, exist_ok=True)
+        (temp_working_path / docs).parent.mkdir(parents=True, exist_ok=True)
 
         try:
-            (temp_working_path / docs_path).symlink_to(
-                Path.cwd() / docs_path,
+            (temp_working_path / docs).symlink_to(
+                Path.cwd() / docs,
                 target_is_directory=True,
             )
         except FileExistsError:
             pass
 
         markdown_to_pot(
-            docs_path=docs_path,
+            docs=docs,
             working_path=temp_working_path,
         )
 
 
 def main():
-    # Generate primary content POT files.
-    generate_pot_files(Path("docs"))
-    # # Generate shared content POT files.
-    generate_pot_files(Path("src/beeware_docs_tools/shared_content"))
+    args = parse_args()
+    # Generate POT files.
+    generate_pot_files(args.docs_directory)
 
 
 if __name__ == "__main__":

src/beeware_docs_tools/shared_content/locales/de/translations.po

@@ -2,14 +2,14 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-09-04 00:03-0400\n"
+"POT-Creation-Date: 2025-09-13 15:51-0500\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Translate Toolkit 3.16.0\n"
+"X-Generator: Translate Toolkit 3.16.1\n"
 
 #: src/beeware_docs_tools/shared_content/en/style_guide.md:1
 #, fuzzy

src/beeware_docs_tools/shared_content/locales/fr/translations.po

@@ -2,14 +2,14 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-09-04 00:03-0400\n"
+"POT-Creation-Date: 2025-09-13 15:51-0500\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Translate Toolkit 3.16.0\n"
+"X-Generator: Translate Toolkit 3.16.1\n"
 
 #: src/beeware_docs_tools/shared_content/en/style_guide.md:1
 #, fuzzy

tox.ini

@@ -17,7 +17,9 @@ deps =
 commands:
     !lint-!all-!translate-!machine-!live-!en-!de-!fr : build_md_translations {posargs} --source-code=src en
     translate : build_pot_translations
+    translate : build_pot_translations -d src/beeware_docs_tools/shared_content
     translate : build_po_translations de fr
+    translate : build_po_translations de fr -d src/beeware_docs_tools/shared_content
     translate : update_machine_translations --soft-fail --docs {[docs]docs_dir} --docs {[docs]shared_content_dir} de fr
     lint : markdown-checker --dir {[docs]docs_dir} --func check_broken_urls
     lint : pyspelling