Multi-language ads
Run one ad in several languages — Meta serves each person their own version and falls back to your default.
Add languages to a single-image or single-video ad and Meta builds one ad that serves each person the version for their language. Anyone whose language you have not added sees defaultLanguage. This is Meta's dynamic language optimisation.
When to use this
You have the same ad in several languages and want one ad, one budget, and Meta deciding which version each person sees — rather than one ad per language.
Example body
POST /meta/launches
{
"adAccountId": "01H8Y4...",
"ads": [
{
"adName": "Spring Sale — multi-language",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "single_image",
"creatives": [{ "_id": "01H8YA..." }]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765"
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Up to 40% off this spring.",
"defaultHeadline": "Spring Sale",
"adDescription": "Free shipping over $50.",
"webLink": "https://example.com/spring",
"defaultLanguage": 6,
"languages": [
{
"locale": 5,
"primaryText": "Bis zu 40 % Rabatt.",
"headline": "Frühlingsangebot",
"description": "Kostenloser Versand ab 50 $.",
"webLink": "https://example.com/de/spring",
"creative": { "_id": "01H8YB..." }
},
{
"locale": 48,
"primaryText": "40% வரை தள்ளுபடி.",
"headline": "வசந்த கால விற்பனை",
"description": "$50க்கு மேல் இலவச ஷிப்பிங்.",
"webLink": "https://example.com/ta/spring"
}
]
}
]
}The German entry brings its own image; Tamil omits creative and reuses the ad's. Locale ids come from the Locale reference — 6 is English (US), 5 German, 48 Tamil.
Full schema: Create a launch.
Rules
- Single image and single video only. Sending
languageswith any othergroupType, or alongsideadId/organicPostDetails, returns400 "languages" is not allowed. defaultLanguageis required wheneverlanguagesis present, and must not be repeated inside it.- Up to 49 languages plus the default — 50 in total. Meta rejects 51 with
Too many assets of same type in ad asset feed. - No two languages from the same group. Meta serves Spanish and Spanish (Spain) from one rule, so picking both is ambiguous. See Language groups.
- Not with text variations.
languagesandprimaryTextVariations/headlineVariations/descriptionVariationsneed the same part of the Meta creative. Sending both returns400 An ad cannot use both languages and text variations. - Every language's creative must match the ad's media type. An image ad cannot take a video for one language.
All or nothing per field
primaryText and headline fall back to the ad's defaults per language, so you can omit them freely.
description and webLink do not behave that way. Supply them for every language or for none — a partial set is rejected by Meta:
Too few News Feed link description texts were provided when creating an asset.
Please make sure that the asset contains a News Feed link description text for each language.Not available on
Meta excludes dynamic language optimisation from:
- Partnership ads
- Advantage+ sales campaigns using Advantage+ creative
- Ads whose destination is an Instant Experience or a messaging app
A language-specific webLink applies only to the traffic, engagement, leads and sales objectives. On any other objective every language uses the ad's own webLink.
Verifying the result
A 202 from POST /meta/launches only means the batch was queued. Poll Get launch until it leaves pending / processing, then read the Meta creative. A correctly built multi-language creative has:
asset_feed_spec.optimization_type: "LANGUAGE"- one
asset_customization_rulesentry per language, the default one carryingis_default: true object_story_speccontaining onlypage_idandinstagram_user_id— the media lives inasset_feed_spec
Rules are keyed on the whole language group, so an English default reads [6, 24] and a Spanish language reads [7, 23].
Errors
| Status | Message | Cause |
|---|---|---|
| 400 | "languages" is not allowed | Used on a grouped format, an existing ad, or an organic post |
| 400 | defaultLanguage is required when languages are provided | languages sent without defaultLanguage |
| 400 | languages must not repeat defaultLanguage | The default appears again inside languages |
| 400 | "languages[n]" contains a duplicate value | The same locale twice |
| 400 | "languages" must contain less than or equal to 49 items | More than 49 entries |
| 400 | An ad cannot use both languages and text variations | Combined with any *Variations array |
| Launch failure | Too few News Feed link description texts | description on some languages but not all |
| Launch failure | Too few body texts / Too few headline texts | Two languages resolving to one rule — usually two members of the same language group |
