feat(news): school news in the guardian's language, with the AI notice and the original one click away (#837)

* docs(openspec): news-item-translation, school news in the reader's language with the AI notice

* feat(news): a news item keeps its AI translations next to the original, and the feed reads in the guardian's language

* feat(portal): a news page that shows the AI notice and the original one click away

Author: rubenvdlinde

docs/operations/translated-messages.md

@@ -17,13 +17,15 @@ Under **Messages** the parent picks a language in **Show messages in**. Each mes
 
 The parent's own messages are never translated. **As written** switches translation off.
 
+School news follows the same choice. Under **News** each item shows its title, then its text in the parent's language with the same notice and the same **Show the original text** button. The title stays as the school wrote it. The **News** page carries the same language picker, so a parent without conversations can pick a language there.
+
 ## What you need
 
 Translation runs through Hermiq's message translation feature. It arrives switched off. Your data protection officer acknowledges it under **Settings > Algorithm register** in Hermiq, and an administrator enables it. Until then, and on an instance without Hermiq, every message shows as written. Nothing breaks.
 
 ## What is kept
 
-The message keeps its original text. Each translation is stored next to it, once per language, with the language it came from, the model that made it and the notice sentence. A message is translated the first time someone reads it in that language, three messages per page load at most; the rest follow on the next load.
+The message, or news item, keeps its original text. Each translation is stored next to it, once per language, with the language it came from, the model that made it and the notice sentence. A message is translated the first time someone reads it in that language, three messages per page load at most; the rest follow on the next load.
 
 ## Endpoints
 
@@ -32,5 +34,6 @@ The message keeps its original text. Each translation is stored next to it, once
 | `GET` | `/portal/api/identity/details` | The account holder's own details, including `messageLanguage` |
 | `PATCH` | `/portal/api/identity/details` | Set `messageLanguage` to a language tag such as `ar`, or `""` for as written |
 | `GET` | `/api/messages/threads/{id}/messages` | The messages; a translated one carries `translation` |
+| `GET` | `/api/news/feed` | The published news for this parent; a translated item carries `translation` |
 
 A `translation` holds `targetLanguage`, `text`, `translatedByAi`, `sourceLanguage`, `sourceLanguageDetected`, `model`, `originalRef`, `disclosure` and `disclosureLanguage`.

l10n/en.js

@@ -1519,7 +1519,9 @@
         "Grant this request?": "Grant this request?",
         "{name} can then see the cases of {party}.": "{name} can then see the cases of {party}.",
         "Access granted.": "Access granted.",
-        "Request refused.": "Request refused."
+        "Request refused.": "Request refused.",
+        "Plain text / markdown body, as written. An AI translation for a reader's language is kept in translations, never here.": "Plain text / markdown body, as written. An AI translation for a reader's language is kept in translations, never here.",
+        "Server-managed. One entry per language this news item was translated into by AI: the translated text, the source language, the model, a reference to this item and the disclosure sentence. The body stays as written.": "Server-managed. One entry per language this news item was translated into by AI: the translated text, the source language, the model, a reference to this item and the disclosure sentence. The body stays as written."
     },
     "plurals": "",
     "pluralForm": "nplurals=2; plural=(n != 1);"

l10n/en.json

@@ -1577,7 +1577,9 @@
         "Grant this request?": "Deze aanvraag toekennen?",
         "{name} can then see the cases of {party}.": "{name} kan dan de zaken van {party} zien.",
         "Access granted.": "Toegang toegekend.",
-        "Request refused.": "Aanvraag geweigerd."
+        "Request refused.": "Aanvraag geweigerd.",
+        "Plain text / markdown body, as written. An AI translation for a reader's language is kept in translations, never here.": "Platte tekst of markdown, zoals geschreven. Een AI-vertaling naar de taal van een lezer staat in de vertalingen, nooit hier.",
+        "Server-managed. One entry per language this news item was translated into by AI: the translated text, the source language, the model, a reference to this item and the disclosure sentence. The body stays as written.": "Beheerd door de server. Eén regel per taal waarin dit nieuwsbericht door AI is vertaald: de vertaalde tekst, de brontaal, het model, een verwijzing naar dit bericht en de vermelding dat AI het vertaalde. De tekst zelf blijft zoals geschreven."
     },
     "plurals": "",
     "pluralForm": "nplurals=2; plural=(n != 1);"

l10n/nl.js

@@ -31,6 +31,7 @@
 
 use OCA\Portaliq\AppInfo\Application;
 use OCA\Portaliq\Auth\PortalProtected;
+use OCA\Portaliq\Service\Identity\PortalSelfServiceService;
 use OCA\Portaliq\Service\NewsFeedReader;
 use OCA\Portaliq\Service\NewsReadReceiptService;
 use OCA\Portaliq\Service\PortalSessionService;
@@ -55,12 +56,17 @@ class NewsGuardianController extends Controller implements PortalProtected {
 	 * @param PortalSessionService $session Resolves the subject from the bearer.
 	 * @param NewsFeedReader $feedReader The guardian-scoped read path.
 	 * @param NewsReadReceiptService $readReceipts Idempotent read-receipt recording.
+	 * @param PortalSelfServiceService|null $selfService Reads the reader's own `messageLanguage`
+	 *                                                   (news-item-translation). Nullable and
+	 *                                                   trailing so a controller built by hand
+	 *                                                   keeps its old shape.
 	 */
 	public function __construct(
 		IRequest $request,
 		private readonly PortalSessionService $session,
 		private readonly NewsFeedReader $feedReader,
 		private readonly NewsReadReceiptService $readReceipts,
+		private readonly ?PortalSelfServiceService $selfService = null,
 	) {
 		parent::__construct(appName: Application::APP_ID, request: $request);
 	}//end __construct()
@@ -71,6 +77,7 @@ public function __construct(
 	 * @return JSONResponse
 	 *
 	 * @spec openspec/changes/news-and-newsletter-authoring/specs/portaliq-cms/spec.md#requirement-a-newsitem-is-authored-per-school-group-or-child-and-tracks-read-receipts
+	 * @spec openspec/changes/news-item-translation/specs/guardian-message-translation/spec.md#requirement-a-news-item-keeps-its-ai-translations-next-to-the-original
 	 */
 	#[PublicPage]
 	#[NoCSRFRequired]
@@ -81,7 +88,13 @@ public function feed(): JSONResponse {
 			return new JSONResponse(['error' => 'unauthorized'], Http::STATUS_UNAUTHORIZED);
 		}
 
-		return new JSONResponse($this->feedReader->feedFor(subjectRef: (string)($subject['subjectRef'] ?? '')));
+		$subjectRef = (string)($subject['subjectRef'] ?? '');
+		$language   = '';
+		if ($this->selfService !== null && $subjectRef !== '') {
+			$language = $this->selfService->messageLanguage(subjectRef: $subjectRef);
+		}
+
+		return new JSONResponse($this->feedReader->feedFor(subjectRef: $subjectRef, language: $language));
 	}//end feed()
 
 	/**

l10n/nl.json

@@ -63,14 +63,17 @@ public function __construct(
 	 * @param array<int, array<string, mixed>> $messages The thread's messages, already authorised.
 	 * @param string $readerRef The reader's own subjectRef.
 	 * @param string $language The reader's `messageLanguage`, '' for as written.
+	 * @param string $schema The schema the rows live in and are stored back to:
+	 *                       `guardianMessage`, or `newsItem` for the news feed.
 	 *
 	 * @return array<int, array<string, mixed>> The same messages, each carrying
 	 *                                          `translation` when one applies.
 	 *
 	 * @spec openspec/changes/translated-message-notice/specs/guardian-message-translation/spec.md#requirement-translation-work-per-request-is-bounded-and-skips-what-needs-none
 	 * @spec openspec/changes/translated-message-notice/specs/guardian-message-translation/spec.md#requirement-the-stored-message-keeps-both-texts-and-the-provenance
+	 * @spec openspec/changes/news-item-translation/specs/guardian-message-translation/spec.md#requirement-a-news-item-keeps-its-ai-translations-next-to-the-original
 	 */
-	public function forReader(array $messages, string $readerRef, string $language): array {
+	public function forReader(array $messages, string $readerRef, string $language, string $schema = self::MESSAGE_SCHEMA): array {
 		if ($language === '') {
 			return $messages;
 		}
@@ -84,7 +87,7 @@ public function forReader(array $messages, string $readerRef, string $language):
 			$entry = $this->storedEntry(message: $message, language: $language);
 			if ($entry === null && $budget > 0) {
 				$budget--;
-				$entry = $this->translateAndStore(message: $message, language: $language);
+				$entry = $this->translateAndStore(message: $message, language: $language, schema: $schema);
 			}
 
 			if ($entry !== null && $this->differs(entry: $entry, language: $language) === true) {
@@ -118,12 +121,13 @@ private function storedEntry(array $message, string $language): ?array {
 	 *
 	 * @param array<string, mixed> $message The message.
 	 * @param string $language The reader's language.
+	 * @param string $schema The schema the row is stored back to.
 	 *
 	 * @return array<string, mixed>|null The new entry, or null.
 	 *
 	 * @spec openspec/changes/translated-message-notice/specs/guardian-message-translation/spec.md#requirement-the-stored-message-keeps-both-texts-and-the-provenance
 	 */
-	private function translateAndStore(array $message, string $language): ?array {
+	private function translateAndStore(array $message, string $language, string $schema): ?array {
 		$id = $this->store->rowId(row: $message);
 		if ($id === null) {
 			return null;
@@ -132,7 +136,7 @@ private function translateAndStore(array $message, string $language): ?array {
 		$entry = $this->client->translate(
 			text: (string)$message['body'],
 			targetLanguage: $language,
-			originalRef: 'portaliq:' . self::MESSAGE_SCHEMA . ':' . $id
+			originalRef: 'portaliq:' . $schema . ':' . $id
 		);
 		if ($entry === null) {
 			return null;
@@ -143,7 +147,7 @@ private function translateAndStore(array $message, string $language): ?array {
 		unset($stored['translation'], $stored['@self']);
 		$stored['translations']   = array_values((array)($message['translations'] ?? []));
 		$stored['translations'][] = $entry;
-		$this->store->save(schema: self::MESSAGE_SCHEMA, object: $stored, uuid: $id);
+		$this->store->save(schema: $schema, object: $stored, uuid: $id);
 
 		return $entry;
 	}//end translateAndStore()

lib/Controller/NewsGuardianController.php

@@ -31,6 +31,7 @@
 
 namespace OCA\Portaliq\Service;
 
+use OCA\Portaliq\Service\Messaging\GuardianMessageTranslator;
 use Psr\Container\ContainerInterface;
 use Psr\Log\LoggerInterface;
 use Throwable;
@@ -55,12 +56,17 @@ class NewsFeedReader {
 	 * @param GuardianAudienceFixtureReader $audienceReader Resolves the guardian's own audience.
 	 * @param NewsPhotoConsentGate $photoGate Redacts photos per the consent gate.
 	 * @param LoggerInterface $logger The logger.
+	 * @param GuardianMessageTranslator|null $translator Shows a news body in the reader's
+	 *                                                   language (news-item-translation).
+	 *                                                   Nullable and trailing so a reader
+	 *                                                   built by hand keeps its old shape.
 	 */
 	public function __construct(
 		private readonly ContainerInterface $container,
 		private readonly GuardianAudienceFixtureReader $audienceReader,
 		private readonly NewsPhotoConsentGate $photoGate,
 		private readonly LoggerInterface $logger,
+		private readonly ?GuardianMessageTranslator $translator = null,
 	) {
 	}//end __construct()
 
@@ -69,13 +75,21 @@ public function __construct(
 	 * audience. An empty/unresolvable audience yields an empty feed, never an
 	 * error (fail-closed empty).
 	 *
+	 * With a `$language` the body of each item is shown in it: a stored AI
+	 * translation is reused, at most three new ones are made per request and
+	 * stored on the item, and the item carries `translation` (decision D24).
+	 * Translation runs on the STORED rows, before the photo consent gate
+	 * redacts the reader's copy, so a stored translation never drops a photo.
+	 *
 	 * @param string $subjectRef The guardian's own subjectRef.
+	 * @param string $language The reader's `messageLanguage`, '' for as written.
 	 *
 	 * @return array<int, array<string, mixed>>
 	 *
 	 * @spec openspec/changes/news-and-newsletter-authoring/specs/portaliq-cms/spec.md#requirement-a-newsitem-is-authored-per-school-group-or-child-and-tracks-read-receipts
+	 * @spec openspec/changes/news-item-translation/specs/guardian-message-translation/spec.md#requirement-a-news-item-keeps-its-ai-translations-next-to-the-original
 	 */
-	public function feedFor(string $subjectRef): array {
+	public function feedFor(string $subjectRef, string $language = ''): array {
 		$audience = $this->audienceReader->resolveAudience(subjectRef: $subjectRef);
 		$rows = $this->findAllPublished(schema: 'newsItem');
 
@@ -94,10 +108,14 @@ public function feedFor(string $subjectRef): array {
 				continue;
 			}
 
-			$matched[] = $this->photoGate->apply(item: $row);
+			$matched[] = $row;
 		}
 
-		return $matched;
+		if ($this->translator !== null && $language !== '') {
+			$matched = $this->translator->forReader(messages: $matched, readerRef: $subjectRef, language: $language, schema: 'newsItem');
+		}
+
+		return array_map(fn (array $row): array => $this->photoGate->apply(item: $row), $matched);
 	}//end feedFor()
 
 	/**

lib/Service/Messaging/GuardianMessageTranslator.php

@@ -2,7 +2,7 @@
   "openapi": "3.0.0",
   "info": {
     "title": "portaliq demo data",
-    "version": "1.0.3",
+    "version": "1.0.4",
     "description": "Demo data covering every schema this app supplies, offered as the first step of the app's setup walkthrough. Generated from the schemas themselves, so every object satisfies the schema that will validate it."
   },
   "x-openregister": {
@@ -2505,7 +2505,8 @@
             "subjectRef": "Voorbeeld Subjectref 1",
             "readAt": "2026-03-01T09:00:00+00:00"
           }
-        ]
+        ],
+        "translations": []
       },
       {
         "@self": {
@@ -2514,7 +2515,7 @@
           "slug": "newsitem-voorbeeld-title-2-2"
         },
         "title": "Voorbeeld Title 2",
-        "body": "Voorbeeld Body 2",
+        "body": "De school is vrijdag gesloten vanwege een studiedag.",
         "target": {
           "schoolRef": "Voorbeeld Schoolref 2",
           "groupRefs": [
@@ -2534,6 +2535,20 @@
             "subjectRef": "Voorbeeld Subjectref 2",
             "readAt": "2026-03-02T09:00:00+00:00"
           }
+        ],
+        "translations": [
+          {
+            "targetLanguage": "ar",
+            "text": "المدرسة مغلقة يوم الجمعة بسبب يوم دراسي للمعلمين.",
+            "translatedByAi": true,
+            "sourceLanguage": "nl",
+            "sourceLanguageDetected": true,
+            "model": "nextcloud",
+            "originalRef": "portaliq:newsItem:demo-2",
+            "disclosure": "تُرجم بواسطة الذكاء الاصطناعي. اللغة الأصلية: الهولندية. قد تحتوي هذه الترجمة على أخطاء.",
+            "disclosureLanguage": "ar",
+            "translatedAt": "2026-09-28T09:00:00+00:00"
+          }
         ]
       },
       {
@@ -2563,7 +2578,8 @@
             "subjectRef": "Voorbeeld Subjectref 3",
             "readAt": "2026-03-03T09:00:00+00:00"
           }
-        ]
+        ],
+        "translations": []
       },
       {
         "@self": {

lib/Service/NewsFeedReader.php

@@ -3,7 +3,7 @@
     "info": {
         "title": "Portaliq Register",
         "description": "Portaliq — the fleet's shared external portal for clients and suppliers (ADR-046). Holds every portal account, page, session, submission, message, notification, audit entry, traffic record, form and landing-page submission the app reads and writes.",
-        "version": "0.36.2"
+        "version": "0.37.0"
     },
     "x-openregister": {
         "type": "application",
@@ -20,7 +20,7 @@
                 "slug": "portaliq",
                 "title": "Portaliq Register",
                 "description": "Portaliq — the fleet's shared external portal for clients and suppliers (ADR-046). Holds every portal account, page, session, submission, message, notification, audit entry and traffic record the app reads and writes.",
-                "version": "0.36.2",
+                "version": "0.37.0",
                 "schemas": [
                     "exampleDocument",
                     "glossaryTerm",
@@ -6466,7 +6466,7 @@
             "newsItem": {
                 "slug": "newsItem",
                 "icon": "FileDocument",
-                "version": "0.1.0",
+                "version": "0.2.0",
                 "title": "News item",
                 "authorization": {
                     "read": [
@@ -6495,7 +6495,7 @@
                     "body": {
                         "title": "Body",
                         "type": "string",
-                        "description": "Plain text / markdown body. Not translated by this change (see hermiq's message-translation-delegate).",
+                        "description": "Plain text / markdown body, as written. An AI translation for a reader's language is kept in translations, never here.",
                         "example": "De herfstvakantie loopt van 19 tot 23 oktober."
                     },
                     "target": {
@@ -6579,6 +6579,15 @@
                             }
                         },
                         "example": []
+                    },
+                    "translations": {
+                        "title": "Translations",
+                        "type": "array",
+                        "description": "Server-managed. One entry per language this news item was translated into by AI: the translated text, the source language, the model, a reference to this item and the disclosure sentence. The body stays as written.",
+                        "items": {
+                            "type": "object"
+                        },
+                        "example": []
                     }
                 }
             },