Localization for In-App Automation
Localizing your messages helps you reach your audience with content specific to their language settings without creating independent messages for each language.
Airship’s localization feature provides a way to send a single message with multiple localizations. You can prepare localizations based on language information or LocaleThe combination of a language and country. A user’s locale is determined by their device settings. for more specific, regional localizations. Airship delivers localized messages to your audience according to language and country information gathered by the Airship SDK.
For example, if you prepared a German localization, users with their language set to German will receive the German localization of your message. If you want to make your message more regionally specific, you could add German localizations for both Germany and Austria. Users with their language preferences set to German would receive different messages depending on whether their country/region settings are set to Germany or Austria.
You can create localized content using:
- The Message and In-App Automation composers.
/schedulesAPIs, with a
localizationsarray in your request
All message types for the App channel are supported: push notifications, in-app messages, and Message Center messages. In the Message composer, you also have the option of selecting a content template.
Localization for In-App Automation includes support for Custom HTML messages.
This document is for the In-App Automation composer. For the Message composer and the APIS, see: Localization.
Create localized content
To localize a message with In-App Automation, you will create an CSV file containing the content for your language variants, then upload it in the composer, where you can preview and edit each version of the message. Airship generates localized messages for each language or locale in your CSV. Localization for In-App Automation requires minimum SDKs: iOS 11.0, Android 10.0.
Format localization CSV
First you must create a CSV containing translations for each language and country combination that you want to localize your message for. The first row in your CSV contains your column headers. Subsequent rows in the CSV represent your localizations, organized by language and country code. The only required value in a localization CSV is
id.language, for all rows except the default localization row.
id.language,id.country,header,body,button1,button1.link ,,Hi there!,Whatcha doin?,Not much,https://www.example.com/nada de,DE,Guten tag,Was machst du gerade?,Nicht viel,https://www.example.com/de/nada
Your CSV must contain:
- A row with empty
id.countryvalues; this row represents the default localization for the message and goes to users who do not match any of the language/country combinations in your CSV.
- Additional column headers corresponding to
data-ua-idvalues for the custom HTML elements that you want to localize. Custom HTML messages only.
Except for the default row,
id.language is required;
id.country is optional.
If you want to avoid sending a message with the default localization values to members of your audience who don’t match the language and country information specified in your localized CSV, you can target specific users by localeThe combination of a language and country. A user’s locale is determined by their device settings. in the Audience step. This will ensure that your message only goes to users with the locales specified in your CSV.
Column headers for ALL messages:
id.language— The two-letter language code associated with this translation. Acceptable values are defined by ISO 639-1 .
id.country— The two-letter country code associated with this translation. Acceptable values are defined by ISO 3166-1 .
<custom>.key— Any header ending in
.keyis treated as a “custom key” or “extra”, where the key is the section of the header preceding .key (e.g., the key for custom.key would be “custom”). The value in each row represents the localized information that you want to pass to the key.
Column headers for Banner, Modal, and Fullscreen messages:
header— Sets value for Header text.
body— (Required) - Sets value for Body text.
media— Sets URL for Media field. HTTPS required. URL must be accessible by your mobile audience.
- Image formats: JPEG, JPG, PNG, GIF
- Video formats: MPEG, MPEG2, MP4, YouTube
If you intend to use uploaded media in your message, enter a placeholder URL in your CSV file, then use the Upload option for media in the Content step after uploading the CSV. See: Localization for In-App Automation.
footer— Sets value for Footer text. Fullscreen and Modal styles only.
footer.<Action>— Associates an action with tapping the footer. Deep Link and Link actions are supported for the footer. Fullscreen and Modal styles only.
button<N>— Sets value for Nth button text. The number of supported buttons varies per layout. At least 1 is required for all layouts.
button<N>.<Action>— Associates an action with the Nth button. The number of supported buttons varies per layout. At least 1 is required for all Layouts).
Column headers for Custom HTML messages:
See: Format localization CSV and HTML.
Upload localization CSV
Follow these steps to enable localization and upload your CSV in the In-App Automation composer.
These steps cover enabling localization and adding content only — see the In-App Automation composer documentation for the full process.
In the Settings step, enable Localization:
In the Content step, upload your CSV:
Click Choose File and select the CSV file containing your localizations.
Click Create Localizations.
Select from the dropdown menu to view content for each localization and edit as necessary. Available fields and options vary per message style.
Media: Enter an HTTPS URL that will be accessible by your mobile audience. If your Airship plan includes CDN support, you can also upload media or select from previously uploaded media.
- Select Upload and click Insert Media.
Click Choose file and select a file to upload, or select from previous uploads.
- The default sort order is most recent upload first.
- You can search by file name or keyword.
- A file preview appears after upload or selection. Click to preview audio and video files.
(Optional) Add or edit keywords for the file to help organize your uploads.
- Enter a term in the search field below the preview and select from results, or click Add keyword: [term].
- Click to remove a keyword.
Click Insert selected media.
- Select Upload and click Insert Media.
See also: Media library. Contact Support if you are interested in enabling CDN media hosting.
Buttons: Enter button label text and click Add button. Banner and modal messages support up to two buttons. Fullscreen messages support up to five buttons. If there are two buttons total, choose a button layout: separate, joined, or stacked.
Custom KeysAdditional key-value pairs in your push notification payload for use by custom code in your app. You can use custom keys to pass additional campaign identifiers for analytics, pass user information to the device, control the look and feel of the app, provide image links, etc. : Enter a key and value. Click Add another for additional keys.
When you have finished adding localizations, click in the header and complete the rest of the steps in the composer.
You can Target Specific Users by locale to align your audience with your localizations. Matching your audience with your message’s languages or locales ensures that your audience does not receive the default message. See also: Segmenting Your Audience.
Create localized content for Custom HTML
You can localize Custom HTML messages for In-App Automation. You will need to format your HTML with
data-ua-id attributes representing the parts of your message you want to localize, and you will need a CSV file containing your translations.
Format localization CSV and HTML
When building your Custom HTML message, you will assign a
data-ua-id attribute with a unique string value to any element that you want to localize. You will then represent your
data-ua-id attributes as column headings in your localization CSV; Airship uses these
data-ua-id values to associate localized text or values with your Custom HTML. For example, you can populate localized text for an
h2 element with
data-ua-id="flooble" by placing a
flooble heading in your CSV.
By default, Airship treats elements with
data-ua-id as text, but you can also add additional “type” attributes to elements to tell Airship how to render localized values in your HTML message.
data-ua-text— Airship inserts the localized value as a plain text node into the parent element, with new lines converted into
data-ua-link— Indicates that the element supports “actions”. This places an anchor tag (
<a>) immediately inside the element, wrapping the contents of the element. You determine the type of action and the action value in your CSV. You can combine this with other attribute types, wrapping the total contents of the element in an anchor tag.
data-ua-image— Airship will insert an
<img>tag in the parent element, using the translated value as the
data-ua-video— Airship will insert a
<video>tag in the parent element using the translated value as the video’s
src. The video tag also includes a
<div data-ua-id="header" data-ua-text></div> <div data-ua-id="hero" data-ua-image></div> <div data-ua-id="body" data-ua-text></div> <div data-ua-id="button" data-ua-link></div>
id.language,id.country,header,hero,body,button1,button1.link ,,Hey dude,https://example.com/image.jpg,check this out :point_up:,cool,https://example.com/coolimage es,MX,hola amigo,https://example.com/es/image.jpg,mira esto :point_up:,bueno,https://example.com/es/coolimage
Prepare your CSV as explained in Format localization CSV and with the HTML-specific information in this section.
Localization actions For Custom HTML
You can assign an action to any element in your custom HTML that has a
data-ua-link attribute. You assign actions by adding a column in your CSV with the
data-ua-id of an element and
.<action_type>. For example,
flooble.deep_link would represent a deep link action for an element with a
flooble; the value in each row would be the deep link for each localization.
You must set your HTML actions in your localization CSV. You cannot set HTML actions in the composer. (You can set and edit actions in the composer for non-HTML messages.)
deep_link- Deep Link action.
link- Link (external URL) action; the corresponding value must be a valid URL.
share- Share action; the corresponding value is the text provided to the share dialog.
push_opt_in- Push Opt-In action; the corresponding value must be “true” to enable.
location_opt_in- Location Opt-In action; the corresponding value must be “true” to enable.
app_rating- App Rating action; the corresponding value must be “true” to enable.
app_rating.title- Sets the title of the App Rating modal; this key is optional and ignored if
app_ratingis not “true”.
app_rating.body- Sets body of App Rating modal; this key is optional and ignored if
app_ratingis not “true”.
dismiss- Dismiss the In-App Automation message; the corresponding value must be “true” to enable.
add_tags- Add Tags action; the corresponding value must be a valid tag.
remove_tags- Remove Tags action; the corresponding value must be a valid tag.
Adding and removing multiple tags
Support for multiple actions on each button is available from Android SDK 14.1 and iOS SDK 14.2, by creating multiple headers. For example:
If you want to add or remove multiple tags using the CSV upload, you will need to use URL Encoding to format the collection of tags in the file.
A collection of tags in a column would be wrapped in square brackets
 and each tag separated by a comma and wrapped in quotes
"". Then using URL encoding for the
] characters, the following example:
id.language,id.country,header,body,button1,button1.dismiss,button1.add_tags,button1.remove_tags ,,Hi there!,What're you doing?,Walking the dog,true,["coffee","tea"],["soda","water"]
Would be formatted this way:
id.language,id.country,header,body,button1,button1.dismiss,button1.add_tags,button1.remove_tags ,,Hi there!,What're you doing?,Walking the dog,true,%5B%22coffee%22%2C%22tea%22%5D%,5B%22soda%22%2C%22water%22%5D
Upload localized CSV and Custom HTML
Follow these steps to upload your localization CSV and HTML in the In-App Automation composer. After enabling localization and selecting the message style, this section covers the Content step only.
These steps cover selecting the message style, enabling localization, and adding content only — see the In-App Automation composer documentation for the full process.
In the Style step, select Custom HTML.
In the Settings step, enable Localization:
In the Content step, upload your HTML and CSV:
For Upload HTML, click Choose File and select your HTML file.
For Upload CSV, click Choose File and select the CSV file containing your localizations. Your localization CSV should also include any actions that you want to occur when a user taps buttons or interacts with your message.
Click Create Localizations to generate a preview of the HTML. Use the dropdown menu to review your localizations.
Click in the header when you are ready to complete the rest of the steps in the composer.