Add documentation for how DAL `translated` fields work and differ from normal fields

[MalteJanz]

When you query data from the DB, either in PHP via the EntityRepository or via the (CRUD) admin / store HTTP API, you often can choose between a field like salesChannel.name and the nested salesChannel.translated.name. Same applies for all Twig templates where you can access entity data (e.g. storefront, document or mail templates, where the latter is even written by merchants)

We should document the difference and specify in which context each variant should be used.

More details / context on the topic can be found in this internal slack discussion:
https://shopware-ag.slack.com/archives/C080HM3C85R/p1773925404226649

but here is the TLDR:

Don't know, if this is documented 🤷‍♂️

salesChannel.name is the plain value for that specific language
salesChannel.translated.name is the inherited name

EN -> DE -> AT
SalesChannel -> Verkaufskanal -> null

For AT (if AT inherit from DE)
salesChannel.name: null
salesChannel.translated.name: Verkaufskanal

For AT (if AT inherit from DE and DE is also null)
salesChannel.name: null
salesChannel.translated.name: SalesChannel

For DE
salesChannel.name: Verkaufskanal
salesChannel.translated.name: Verkaufskanal

it is mainly coming from the DAL being designed to server our CRUD style admin API and UI, there you need to differentiate which value is set from which language or only inherited

but that means when you are in a storefront/saleschannel context you should basically always use translated