Customize different parts of ad creative such as the image, video, text, and body of an ad to reach speakers of different language. Facebook optimizes your ad to show the right language version to the right people.
This helps you to easily set up an ad in multiple languages and deliver the most relevant language version in your ad to a viewer while retaining a broad targeting for the ad. This enables you to have personalized content based on a viewer's spoken language while maintaining cost-efficient ads.
For general information on this feature, see Ads Help Center, Advertise to a multilingual audience. See supported ad campaign objectives.
Multi-Language Ads is one of our three APIs that use asset customization rules.
Before you get started, check restrictions for this product. If your use case meets our specifications, move on to the following steps:
asset_feed_spec
—see also Available Languages.asset_feed_spec
in creative_spec
If you do not have the resources to manually translate your ad, check out our automatic translation service.
asset_feed_spec
Multi-Language Ads creatives are specified using asset_feed_spec
s. An asset feed is a collection of different creative elements, such as image, titles, bodies, and so on. You create an asset_feed_spec
at /adcreative
.
To create an asset_feed_spec
, provide an array of assets for each different language. Add a label to tag each asset to identify the language the asset belongs to. Facebook uses the labels in asset_customization_rules
to group assets together by language. You should provide at least one asset per asset type.
Parameters to provide in asset_feed_spec
include:
Property Name | Description |
---|---|
type: array | Required for Images as Provide this field as an array of |
type: array | Required for Array of Provide this field as an array of |
type: array | Required, but Array of bodies containing primary message of ad. Provide this field as an array of |
type: array | Required, but Array of titles. A short headline in the ad, generally shown next to a link, image or video. Provide this field as an array of |
type: array | Required, but Array of secondary description text, displayed less prominently than bodies or titles. Provide this field as an array of |
type: array | Required, but Array of link URLs. Provide this field as an array of |
type: array | Required. Array of call-to-action-type values. Provide this field as an array of supported call to actions: |
| Required. Array of Facebook ad formats you want to create the ads in. Supported formats are: Provide this field as an array of supported ad formats: |
type: see table below under Asset Customization Rules | Required. Array of asset customization rules. |
Define the assets that appear together for viewers who speak a particular language. Each rule has a customization_spec
which defines the locales of people who view these assets during ad delivery.
Provide exactly one default rule. This rule must include the assets that Facebook displays if someone's preferred language does not match any locales specified in the asset feed. This helps prevent under-delivery of your ads.
Property Name | Description |
---|---|
type: | Required. Define the locales where the assets in this rule should deliver. For supported locales, see Available Languages. |
type: | Required for Label attached to one of the image assets in the asset feed. |
type: | Required for Label attached to one of the video assets in the asset feed. |
type: | Required. Label attached to one of the body assets in the asset feed. |
type: | Required. Label attached to one of the title assets in the asset feed. |
type: | Required. Label attached to one of the description assets in the asset feed. |
type: | Required. Label attached to one of the |
type: boolean | Required. Boolean flag to identify the default rule. You should set exactly one rule with |
The locales you provide in customization_spec
must be locale IDs supported in ads targeting. See Targeting and Placement, Locales. You can search for specific language using the /search
endpoint. Use the q
parameter to search for a specific language name. Leave this parameter blank to get the list of all supported languages:
curl -G \
-d "type=adlocale" \
-d "q=en" \
-d "limit=2" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/v21.0
/search
On success you get a list of languages:
{ "data": [ { "key": 6, "name": "English (US)" }, { "key": 24, "name": "English (UK)" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MAZDZD", } } }
You should use the keys in these search results as locales in your asset customization rules. For more information, see Targeting Search.
You can create an asset feed using the asset_feed_spec
field in POST ad_account_ID/adcreatives
:
curl \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACTOR_ID>",
}' \
-F 'asset_feed_spec={
"ad_formats": ["SINGLE_IMAGE"],
"bodies": [
{
"text": "Try our delicious guacamole recipe!",
"adlabels": [{"name": "english"}],
},
{
"text": "Essayez notre délicieuse recette de guacamole!",
"adlabels": [{"name": "french"}],
},
],
"titles": [
{
"text": "Jaspers Market",
"adlabels": [{"name": "english"}],
},
{
"text": "Jaspers Market",
"adlabels": [{"name": "french"}],
},
],
"descriptions": [
{
"text": "The best avocados!",
"adlabels": [{"name": "english"}],
},
{
"text": "Les meilleurs avocats!",
"adlabels": [{"name": "french"}],
},
],
"link_urls": [
{
"website_url": "www.jaspersmarket.com/en",
"adlabels": [{"name": "english"}],
},
{
"website_url": "www.jaspersmarket.com/fr",
"adlabels": [{"name": "french"}],
},
],
"images": [
{
"hash": "<IMAGE_HASH>",
},
],
"call_to_action_types": ["SHOP_NOW"],
"asset_customization_rules": [
{
"customization_spec": {
"locales": [9,44],
},
"title_label": {"name": "french"},
"body_label": {"name": "french"},
"description_label": {"name": "french"},
"link_url_label": {"name": "french"},
},
{
"is_default": true,
"customization_spec": {
"locales": [24]
},
"title_label": {"name": "english"},
"body_label": {"name": "english"},
"description_label": {"name": "english"},
"link_url_label": {"name": "english"},
},
]
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
On success, you get the ID for the ad creative:
{"id":"238474593777777"}
If your asset_feed_spec
does meet the restrictions below, you see an error.
To create an ad with this ad creative ID, call POST act_AD_ACCOUNT_ID/ads
. Alternatively, to display different languages in your ad, provide the asset_feed_spec
and object_story_spec
in the creative
parameter for the ad.
To verify the new asset_feed_spec
, you call GET
on the ad ID or the ad creative ID:
curl -G \
-d 'fields=object_story_spec,asset_feed_spec' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<CREATIVE_ID>
Preview the different language versions of your ad using the generatepreview
endpoint. Add a dynamic_asset_label
field with an adlabel
in a rule to view a specific language version.
For example, to preview the French version of the above creative:
curl -G \
--data-urlencode 'creative={
"object_story_spec": {
"page_id": "<PAGE_ID>"
},
"asset_feed_spec": {
...
}
}' \
-d 'ad_format=DESKTOP_FEED_STANDARD' \
-d 'dynamic_asset_label=french'
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/generatepreviews
You can use our automatic translation service, if you do not have the resources to manually translate your ad. This capability translates your default ad copy to additional languages, so you can reach a multilingual audience.
The source for the automatic translation can be found in the text assets specified by the default asset customization rule. Automatically translated ad copies are labeled as “Automatically Translated”.
To create an automatically translated version of your ad copy, add autotranslate
to asset_feed_spec
. Then, specify the languages you would like your copy to be translated to. See example:
curl \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACTOR_ID>",
}' \
-F 'asset_feed_spec={
"ad_formats": ["SINGLE_IMAGE"],
"autotranslate": ["fr_XX"],
"bodies": [
{
"text": "Try our delicious guacamole recipe!",
"adlabels": [{"name": "english"}],
}
],
"titles": [
{
"text": "Jaspers Market",
"adlabels": [{"name": "english"}]
}
],
"descriptions": [
{
"text": "The best avocados!",
"adlabels": [{"name": "english"}]
}
],
"link_urls": [
{
"website_url": "www.jaspersmarket.com",
"adlabels": [{"name": "english"}]
}
],
"images": [
{
"hash": "<IMAGE_HASH>"
},
],
"call_to_action_types": ["SHOP_NOW"],
"optimization_type": "LANGUAGE",
"asset_customization_rules": [
{
"is_default": true,
"customization_spec": {
"locales": [6]
},
"title_label": {"name": "english"},
"body_label": {"name": "english"},
"description_label": {"name": "english"},
"link_url_label": {"name": "english"}
}
]
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
The automatically translated copies can be reviewed with a call to the asset_feed_spec
field on the creative.
Any edits to the auto translated copies on the spec will be dropped if the same language is specified on the autotranslate
field. These edits will be replaced by fresh translations from the default ad copy. If you absolutely need the edits, remove the language from the autotranslate
field.
link_urls
You can add a custom link URL to the automatically translated ad version.
To do this, add an language-specific
URL to the link_urls
field along with an adlabel
and add a new rule into asset_customization_rules
with the associated locale codes and link_url_label
for this language.
The following are restrictions and limits on your asset feed.
asset_feed_spec
SINGLE_IMAGE
format, you must provide at least one image.SINGLE_VIDEO
format, you must provide at least one videocall_to_action_types
.call_to_action_type
asset for all objectives. title
s, bodies, description
s and link_urls
, for every language version in the asset feed.adlabels
field.adlabel
. We use this image or video for all the language versions.adlabel
s and provide these labels in your asset customization rule. url_tags
, we append them to the link_url
as parameters for each asset in the ad.APP_INSTALLS
objective, your link_url
should be the same as the ad set's promoted_object.object_store_url
.asset_feed_spec
.is_default
set to true
. This acts as a backup rule and enables ads to display even when someone's locale does not match any of the languages in asset_feed_spec
.LINK_CLICKS
- Website and apps, no Messenger.APP_INSTALLS
- Desktop or mobile apps.CONVERSIONS
- Website and apps, no Messenger. REACH
- All destination types.BRAND_AWARENESS
- All destination types.VIDEO_VIEWS
- All destination typesREACH
- Reach and FrequencyAUCTION
The following translation directions are supported. Use the corresponding dialect code in the autotranslate
field:
Source Language | Target Translation Language | Dialect Code |
---|---|---|
English | Spanish |
|
English | French |
|
English | German |
|
English | Portuguese |
|
English | Italian |
|
English | Arabic |
|
English | Dutch |
|
English | Malay |
|
English | Swedish |
|
English | Indonesian |
|
English | Polish |
|
English | Hindi |
|
English | Danish |
|
English | Turkish |
|
English | Tagalog |
|
English | Romanian |
|
German | English |
|
Arabic | English |
|
Hebrew | English |
|
Spanish | English |
|
Japanese | English |
|
Norwegian | English |
|
French | English |
|
Dutch | English |
|
Swedish | English |
|