adobe / adobe/xdm

Add locale/language variants to paid-media-creative datatype

Open
#2,173 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
266
Forks
380
Avg merge
5d 8h
Merged PRs (30d)
9

Description

## Background

The current `components/datatypes/paid-media/paid-media-creative.schema.json` models a creative with a single set of content fields — one `xdm:title`, `xdm:body`, `xdm:callToAction`, `xdm:destinationURL`, `xdm:assets`, etc.

In production we observe Meta delivering a single ad creative (same `creativeID`) with **different** asset IDs, images, body text, and headlines for different locales. The current schema cannot capture that without losing fidelity.

## Reference

* [Meta Marketing API – Multi-Language Ads](https://developers.facebook.com/docs/marketing-api/multi-language-ads/)
* [Meta `asset_feed_spec` asset customization rules (`language_label`)](https://developers.facebook.com/docs/marketing-api/ad-creative/asset-feed-spec/asset-customization-rules/)
* [Google Ads API – RSA customization](https://developers.google.com/google-ads/api/docs/ads/customize-responsive-search-ads)

## Proposed Change

Add an `xdm:localeVariants` array property to the `paidMediaCreative` definition. Each entry carries:

* `xdm:language` — BCP 47 language tag (`en-US`, `ar-AR`, `fr-FR`, …), pattern reused from existing XDM datatypes (`profile-preferences-details`, `content-component-details`).
* Locale-specific overrides for `xdm:title`, `xdm:body`, `xdm:callToAction`, `xdm:destinationURL`, `xdm:displayURL`, `xdm:trackingURLs`, `xdm:assets`.

Top-level fields stay as the default/fallback (matches Meta's behavior where assets without `language_label` are treated as free-form defaults). To avoid duplication, `creativeAsset` and `creativeTrackingURL` are extracted into shared sub-definitions referenced from both the top-level fields and each locale variant, per [CONTRIBUTING.md – Re-Use and Modularity](../blob/master/CONTRIBUTING.md#re-use-and-modularity).

A new `paid-media-creative.example.4.json` demonstrates English / Arabic / French variants of a single image creative.

## Related

Tracked internally in Adobe Jira AN-451211 (parent design ticket AN-450480).

Contributor guide

Open the contributing guide

Research direction

Start with components/datatypes/paid-media/paid-media-creative.schema.json and compare the language patterns in profile-preferences-details and content-component-details. Read CONTRIBUTING.md's Re-Use and Modularity section, then add the localeVariants structure, shared creativeAsset and creativeTrackingURL definitions, and paid-media-creative.example.4.json; done means the example represents English, Arabic, and French variants without duplicating definitions.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
data
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.