AdnovaDocs
Ad Launcher

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 languages with any other groupType, or alongside adId / organicPostDetails, returns 400 "languages" is not allowed.
  • defaultLanguage is required whenever languages is 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. languages and primaryTextVariations / headlineVariations / descriptionVariations need the same part of the Meta creative. Sending both returns 400 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_rules entry per language, the default one carrying is_default: true
  • object_story_spec containing only page_id and instagram_user_id — the media lives in asset_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

StatusMessageCause
400"languages" is not allowedUsed on a grouped format, an existing ad, or an organic post
400defaultLanguage is required when languages are providedlanguages sent without defaultLanguage
400languages must not repeat defaultLanguageThe default appears again inside languages
400"languages[n]" contains a duplicate valueThe same locale twice
400"languages" must contain less than or equal to 49 itemsMore than 49 entries
400An ad cannot use both languages and text variationsCombined with any *Variations array
Launch failureToo few News Feed link description textsdescription on some languages but not all
Launch failureToo few body texts / Too few headline textsTwo languages resolving to one rule — usually two members of the same language group