Feature: Extend `BabelTranslation` to return resource data and support templating (like `pdoResources`)

[OlegAnTo2000]

Context
BabelTranslation currently returns IDs of translated resources. Internally, the snippet already resolves full modResource objects (or has enough info to fetch them efficiently), but the output is limited to IDs. This forces users to run additional queries/snippets to render actual content.

Problem

• The snippet returns only IDs, so typical usage becomes a two-step process:

  1. call BabelTranslation → get IDs;
  2. pass those IDs into another snippet (e.g., pdoResources) to fetch fields and render HTML.

• This is boilerplate and can cause redundant DB queries.

Requested behavior
Add options to control the return format and templating, similar to pdoResources, while preserving backward compatibility.

Proposed API (non-breaking, default keeps current behavior)

• &return (string, default: ids)

  • ids — current behavior, return comma-separated IDs (or array when &toPlaceholder is used).
  • objects — return raw modResource objects (for advanced users).
  • arrays — return an array of fields (selected via &includeFields).
  • json — return JSON-encoded array of fields.

• &includeFields (string)

  • Comma-separated list of fields/TVs to include when return=arrays|json.
  • Example: pagetitle,uri,introtext,tv.image.

• &tpl / &tplWrapper / &tplNotFound (strings)

  • If &tpl is provided and return=arrays|objects, the snippet renders each item via &tpl and wraps the result via &tplWrapper.
  • If nothing is found, render &tplNotFound.
  • &outputSeparator (string, default: \n) to join items.

• &toPlaceholder (string, optional)

  • Put the result into a placeholder instead of direct output.

Examples

Return IDs (current behavior):

[[BabelTranslation?
  &resourceId=`123,124`
  &contextKey=`de`
  &return=`ids`
]]

Return arrays and render with tpl:

[[BabelTranslation?
  &resourceId=`123,124`
  &contextKey=`de`
  &return=`arrays`
  &includeFields=`id,pagetitle,uri`
  &tpl=`@INLINE <li><a href="[[+uri]]">[[+pagetitle]]</a></li>`
  &tplWrapper=`@INLINE <ul>[[+output]]</ul>`
  &tplNotFound=`@INLINE <p>No translations found</p>`
]]

Return JSON for client-side rendering:

[[BabelTranslation?
  &resourceId=`123`
  &contextKey=`fr`
  &return=`json`
  &includeFields=`id,pagetitle,uri,introtext`
  &toPlaceholder=`translationsJSON`
]]

Acceptance criteria

• Default (&return=ids) preserves current outputs (BC-safe).
• When &return=arrays|json|objects, the snippet returns the requested format without extra DB roundtrips (reuse already-resolved resources where possible).
• When &tpl* params are provided, the snippet can produce ready-to-use HTML similarly to pdoResources.
• Supports &toPlaceholder and &outputSeparator.

Why this helps

• Reduces boilerplate and duplicate queries.
• Makes BabelTranslation usable as a one-stop solution: get translations and render immediately.
• Aligns with familiar pdoResources API, lowering learning curve.

Potential concerns & mitigations

• Performance: Allow &includeFields to limit selected columns/TVs.
• Security: Respect MODX permissions and unpublished/hidden filters exactly as now.
• Complexity: Keep defaults minimal; advanced behavior only when &return/&tpl* provided.