Toelichting-velden, meertalige content (NL+EN)

[alextreme]

Gebruikersverhaal

Als gemeentelijke ontwikkelaar
wil ik dat meertalige content en toelichtingvelden binnen ProductType worden beheerd via een aparte entiteit genaamd "ProductContent"
zodat content eenvoudig in meerdere talen kan worden beheerd en vertaald, zonder dat dit de structuur of prestaties van het ProductType beïnvloedt.

---

Acceptatiecriteria

Nieuwe entiteit: ProductContent

• Een nieuwe entiteit ProductContent wordt toegevoegd aan het datamodel.
• Elke ProductContent bevat de volgende velden:
  • taal: ISO 639-1 taalcode (bijv. "nl", "en"). De default is "nl".
  • titel: De titel van het product in de opgegeven taal (ter bespreking: is dit wel of niet nodig?)
  • content: Een uitgebreide beschrijving van het product in de opgegeven taal, geformateerd in Markdown
  • toelichting: Optioneel veld voor aanvullende toelichting of details in de opgegeven taal.
• Elke ProductContent is gekoppeld aan precies één ProductType.

Meertaligheid

• Een ProductType kan meerdere ProductContent-records hebben, één voor elke ondersteunde taal.
• Bij het opvragen van een ProductType via de API, kan de gewenste taal ook worden gespecificeerd via een queryparameter (bijv. GET /producttypen/:id?taal=nl en GET /producttypen/?taal=nl)
• Als de gevraagde taal niet beschikbaar is, retourneert de API standaard de Nederlandstalige content (taal=nl) of een foutmelding (nader te bepalen)

Validatie en beheer

• Bij het aanmaken of wijzigen van een ProductContent wordt gecontroleerd of:
  • De combinatie van taal en ProductType uniek is.
  • De velden titel en content verplicht zijn.
• Een beheerinterface biedt de mogelijkheid om meertalige content toe te voegen, te wijzigen, of te verwijderen.

Filtering en weergave

• De API ondersteunt filtering en sortering op basis van taal (bijv. GET /productcontent?taal=en).
• Bij een incomplete set vertalingen (bijv. ontbrekende velden in een taal) retourneert de API een waarschuwing met een duidelijke melding.

Documentatie

• De API-documentatie bevat voorbeelden van het instellen en opvragen van meertalige content via de ProductContent-entiteit.
• Voorbeeld-API-aanvragen tonen hoe taal-specifieke content wordt toegevoegd en opgehaald.

---

Definition of Done (DoD)

• De entiteit ProductContent is toegevoegd aan het datamodel en geïmplementeerd in de API.
• Unit tests en integratietests valideren correcte verwerking van meertalige content.
• De API ondersteunt taal-specifieke filtering en retourneert correct fallback-content wanneer nodig.
• Documentatie is bijgewerkt met toelichting, voorbeelden, en validatieregels.

[frankmijn]

Dit is een vrij algemene opdeling van content in een aantal velden. Zeker als je het naar andere bronnen (zoals in ons geval een kennisbank) wil exporteren heb je een fijnmaziger onderscheid nodig in velden. Ik denk dat dan de makkelijkste toevoeging is om titel apart te trekken naar een tabel die er dan zo uitziet:

ProductTitle:

• taal: ISO 639-1 taalcode (bijv. "nl", "en"). De default is "nl".
• titel: De titel van het product in de opgegeven taal (volgens mij wel nodig in verschillende talen)
• gerelateerdProductType: het productType waar dit bij hoort

En dan een aparte tabel ProductContentElements:

• taal: ISO 639-1 taalcode (bijv. "nl", "en"). De default is "nl".
• contentElement: Content geformatteerd in markdown
• label: een label dat je toekent aan dit stukje content, zoals 'voorwaarden', 'openingstijden' en dergelijke. Hier kan je dus een label kiezen. Dit zal ook een vaste (beheerbare) lijst moeten zijn. Waarschijnlijk dus verwijzing naar andere tabel.
• gerelateerdProductType: het productType waar dit bij hoort

En dan ga je nog wat nodig hebben om je ProductContentElements op volgorde te zetten voor publicatie naar verschillende doelen. Dat zou ik niet onderbrengen in ProductContentElements omdat je voor verschillende uitingen mogelijk andere volgordes wil hebben.

Hoop dat dit een beetje overkomt via een comment, maar dit is uiteraard iets om nog verder te bespreken. Ik zou wel willen voorstellen om zo snel mogelijk een voorkant te bouwen op de PDC. Die hoeft niet compleet te zijn, maar dan kan je bepaalde keuzes makkelijker doortesten. Mijn punt blijft dat de PDC an sich weinig is. Het is onderdeel van meerdere ketens en je moet de PDC ook in die ketens plaatsen en testen.

[alextreme]

Uitgangspunt is ook puur tweetalig: NL+EN. Dit betekent dat we de beschikbare talen niet uitbreidbaar maken, in ieder geval niet voor de MVP van OP.

[joeribekker]

we kiezen ervoor om de taal expliciet als query-parameter mee te

Er is al een header hiervoor wat native HTTP is: Accept-Language / Content-Language wat een veel betere aanpak is voor meertaligheid dan een custom header/query-param.

[alextreme]

Besproken qua ProductContentElements:

• onderbouwing: in beplaalde situaties wil je alleen de content die met een bepaalde label is getagged
• labels zijn optioneel
• je mag een label per producttype meerdere keren gebruiken
• volgorde van de contentelements is van belang, dit is voor de publicatie op de website
• de lijst van labels/tags is beheerbaar binnen de omgeving van Open Producten (dus deze lijst is gelijk over alle producttypes)

@VerbeekIT ter info, JoeriD geeft ook aan dat het aanhouden van de Accept-Language de voorkeur geniet om als client de content van een bepaalde taal op te vragen. Mocht je het hier niet mee eens zijn dan dit graag met hem afstemmen