feat(docs): validate owner structured translations

src/govoplan_core/core/modules.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Iterable, Mapping, Sequence
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import Any, Literal, Protocol, TYPE_CHECKING
 
 from govoplan_core.core.information_governance import ModuleInformationGovernance
@@ -687,3 +687,53 @@ class ModuleManifest:
     # runtime module ID changes.
     permission_namespace: str | None = None
     workflow_definitions: tuple["WorkflowDefinitionContribution", ...] = ()
+
+
+def with_documentation_structured_translations(
+    manifest: ModuleManifest,
+    *,
+    locale: str,
+    translations: Mapping[str, Mapping[str, Any]],
+) -> ModuleManifest:
+    """Merge module-owned structured documentation translations by topic id.
+
+    The helper keeps feature prose in its owning module while giving every
+    manifest the same fail-closed merge behavior. Unknown topic ids and
+    incomplete or shape-changing locale maps are rejected immediately.
+    """
+
+    locale = locale.strip()
+    if not locale:
+        raise ValueError("structured documentation locale must not be empty")
+
+    topics_by_id = {topic.id: topic for topic in manifest.documentation}
+    unknown_topic_ids = sorted(set(translations) - set(topics_by_id))
+    if unknown_topic_ids:
+        raise ValueError(
+            "structured documentation translations reference unknown topic ids: "
+            + ", ".join(unknown_topic_ids)
+        )
+
+    localized_topics: list[DocumentationTopic] = []
+    for topic in manifest.documentation:
+        translation = translations.get(topic.id)
+        if translation is None:
+            localized_topics.append(topic)
+            continue
+
+        structured_translations = dict(topic.structured_translations)
+        structured_translations[locale] = translation
+        localized_topic = replace(
+            topic,
+            structured_translation_version=DOCUMENTATION_STRUCTURED_TRANSLATION_VERSION,
+            structured_translations=structured_translations,
+        )
+        issues = documentation_structured_translation_issues(localized_topic)
+        if issues:
+            raise ValueError(
+                f"invalid {locale!r} structured documentation translation for "
+                f"{topic.id!r}: {'; '.join(issues)}"
+            )
+        localized_topics.append(localized_topic)
+
+    return replace(manifest, documentation=tuple(localized_topics))