docs: rewrite translations contributing guide for Crowdin

devenv.nix

@@ -227,8 +227,6 @@ let
     doCheck = true;
   };
 
-  poedit-fixed = pkgs.poedit.override { boost = pkgs.boost186; };
-
   # Grafana datasource provisioning
   grafanaDatasources = pkgs.writeText "datasources.yaml" ''
     apiVersion: 1
@@ -356,8 +354,6 @@ in
     pkgs.gcc
 
     # This seems to be borken on macos
-    # https://github.com/NixOS/nixpkgs/blob/ed142ab1b3a092c4d149245d0c4126a5d7ea00b0/pkgs/by-name/po/poedit/package.nix#L88
-    poedit-fixed
   ]
   # macOS-specific packages
   ++ pkgs.lib.optionals isDarwin [
@@ -804,9 +800,8 @@ in
       echo "Extracting translatable strings from documentation..."
       MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d $DEVENV_ROOT/docs/po $DEVENV_ROOT/docs
       echo ""
-      echo "Translation files generated in docs/po/"
-      echo "Use Poedit or any gettext editor to translate"
-      echo "Then run 'devenv tasks run docs:build' to build translated books"
+      echo "Updated docs/po/messages.pot"
+      echo "Translate on Crowdin: https://crowdin.com/project/cadmus"
     '';
   };
 
@@ -820,12 +815,7 @@ in
     echo "  cadmus-docs-serve     - Serve website locally (http://localhost:3000)"
     echo "  cargo test            - Run tests (after setup)"
     echo "  cargo xtask run-emulator - Run the emulator (after setup)"
-    echo "  cadmus-translate      - Extract translatable strings from documentation"
-    echo ""
-    echo "Translation workflow:"
-    echo "  1. Run 'cadmus-translate' to extract strings into docs/po/"
-    echo "  2. Edit .po files with Poedit or any gettext editor"
-    echo "  3. Run 'devenv tasks run docs:build' to build translated books"
+    echo "  cadmus-translate      - Regenerate docs/po/messages.pot (translations on Crowdin)"
     echo ""
     echo "xtask commands (cargo xtask <cmd> --help for options):"
     echo "  cargo xtask fmt           - Check formatting"

docs/mdbook-mermaid-preprocessor.py

@@ -106,14 +106,28 @@ def render_mermaid_to_png(mermaid_code: str, output_path: Path) -> bool:
         return False
 
 
-def process_chapter_content(content: str, chapter_name: str, png_dir: Path) -> str:
+def relative_mermaid_path(chapter_path: str | None, img_filename: str) -> str:
+    """Return a POSIX path from the chapter file to a PNG in `src/mermaid-images/`."""
+    mermaid_dir = Path("mermaid-images")
+    if chapter_path:
+        chapter_dir = Path(chapter_path).parent
+        rel_dir = os.path.relpath(mermaid_dir, chapter_dir)
+        return f"{rel_dir}/{img_filename}".replace("\\", "/")
+    return f"../mermaid-images/{img_filename}"
+
+
+def process_chapter_content(
+    content: str, chapter_name: str, png_dir: Path, chapter_path: str | None
+) -> str:
     """
     Process chapter content, converting mermaid code blocks to PNG image references.
 
     Args:
         content: The markdown content of the chapter
         chapter_name: Name of the chapter (for PNG filenames)
         png_dir: Directory where PNG files should be saved
+        chapter_path: Source path of the chapter relative to `src/`, used to
+            compute the image link path for nested chapters
 
     Returns:
         Modified content with mermaid blocks replaced by image references
@@ -128,7 +142,7 @@ def replace_mermaid_block(match):
         mermaid_code = match.group(1).strip()
         img_filename = f"{chapter_name}-diagram-{diagram_count}.png"
         img_path = png_dir / img_filename
-        rel_path = f"../mermaid-images/{img_filename}"
+        rel_path = relative_mermaid_path(chapter_path, img_filename)
 
         if render_mermaid_to_png(mermaid_code, img_path):
             return f"![Mermaid Diagram]({rel_path})"
@@ -163,11 +177,12 @@ def process_section(section):
             chapter = section["Chapter"]
             chapter_name = chapter.get("name", "unnamed")
             chapter_name = re.sub(r"[^\w\-]", "-", chapter_name.lower())
+            chapter_path = chapter.get("path")
 
             content = chapter.get("content", "")
             if "```mermaid" in content:
                 chapter["content"] = process_chapter_content(
-                    content, chapter_name, png_dir
+                    content, chapter_name, png_dir, chapter_path
                 )
 
             sub_items = chapter.get("sub_items", [])

docs/src/SUMMARY.md

@@ -38,8 +38,7 @@
   - [Profiling](contributing/telemetry/profiling.md)
 - [Documentation](contributing/documentation.md)
 - [Translations](contributing/translations/index.md)
-  - [UI Strings](contributing/translations/source-code.md)
-  - [Guide](contributing/translations/docs.md)
+  - [For developers](contributing/translations/developers.md)
 - [SQLite & SQLx](contributing/sqlite-sqlx.md)
   - [Library Database](contributing/library-database.md)
   - [Runtime Migrations](contributing/runtime-migrations.md)

docs/src/contributing/translations/developers.md

@@ -0,0 +1,110 @@
+<!-- i18n:skip-start -->
+
+# Translations — for developers
+
+This page is for contributors who change English source strings or
+documentation. Translators should use [Crowdin](https://crowdin.com/project/cadmus)
+or see the main [Translations](index.md) page.
+
+## Adding UI strings
+
+1. Add the message to
+   [`crates/core/i18n/en-GB/cadmus_core.ftl`](https://github.com/ogkevin/cadmus/blob/master/crates/core/i18n/en-GB/cadmus_core.ftl)
+   (kebab-case IDs, sorted within sections — see
+   [`crates/core/AGENTS.md`](https://github.com/ogkevin/cadmus/blob/master/crates/core/AGENTS.md)).
+2. Use `fl!("message-id")` or `fl!("id", var = value)` in Rust.
+3. Other languages are filled in on Crowdin — do not hand-edit locale FTL files
+   unless you have a specific reason.
+4. Run `cargo check -p cadmus-core` to validate message IDs at compile time.
+
+```rust
+let label = crate::fl!("my-new-message");
+let label = crate::fl!("books-loaded", count = book_count);
+```
+
+## Updating documentation translation sources
+
+After changing **user-facing** English docs (`docs/src/**/*.md` outside
+`contributing/`):
+
+```bash
+cadmus-translate   # devenv
+# or: MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build -d docs/po docs
+```
+
+Commit the updated `docs/po/messages.pot` alongside your doc edits. Crowdin
+picks up the new template; translators update locale `.po` files there.
+
+When changing website strings, update
+[`website/messages/en.json`](https://github.com/ogkevin/cadmus/blob/master/website/messages/en.json)
+only — Crowdin handles `website/messages/<lang>.json`.
+
+## You do not need to maintain translated files
+
+After changing English source strings, do **not** hand-edit `docs/po/*.po`,
+`crates/core/i18n/*/*.ftl`, or `website/messages/*.json` for other locales.
+
+Outdated or fuzzy entries in those files are reconciled on Crowdin and synced
+back via the `crowdin` CI workflow (`skip_untranslated_strings: true` on
+export). Missing translations fall back to English at runtime or build time
+until translators catch up.
+
+## Excluding documentation from extraction
+
+These directives apply to the mdBook user guide only. They tell
+`cadmus-translate` which Markdown blocks to omit from `docs/po/messages.pot`.
+
+Use `<!-- i18n:skip -->` before a single block (paragraph, code block, table):
+
+<!-- i18n:skip -->
+
+```markdown
+<!-- i18n:skip -->
+
+This paragraph will not appear in the POT file.
+```
+
+Use `<!-- i18n:skip-start -->` / `<!-- i18n:skip-end -->` to exclude multiple
+consecutive blocks:
+
+<!-- i18n:skip -->
+
+```markdown
+<!-- i18n:skip-start -->
+
+This paragraph is excluded.
+
+And so is this one.
+
+<!-- i18n:skip-end -->
+```
+
+When skip directives appear inside a list, indent them to match the list
+continuation level:
+
+<!-- i18n:skip -->
+
+```markdown
+1. Step one.
+
+   <!-- i18n:skip-start -->
+
+   | Path           | Value  |
+   | -------------- | ------ |
+   | `/mnt/onboard` | stable |
+
+   <!-- i18n:skip-end -->
+
+2. Step two.
+```
+
+## Previewing translated docs locally
+
+```bash
+cargo xtask docs
+cadmus-docs-serve
+```
+
+Use this only to verify builds — translation work happens on Crowdin.
+
+<!-- i18n:skip-end -->