Localize a Custom HTML Message

Localizing your custom HTML In-App Automation messages helps you reach your audience with content specific to their language settings without creating independent messages for each language.

In-App Automation custom HTML messages support localization — you can identify the elements that you want to localize and provide variations for each language you want to reach your audience in.

When composing your message, you will upload a CSV containing localizations for the elements in your custom HTML. Airship sends the appropriate localization to each member of your audience based on device settings gathered by the Airship SDK.

 Tip

For your convenience, when you upload custom HTML, you can download a sample CSV file that contains columns for each data-ua-id associated element that you can pass localized values to.

Formatting Custom HTML for Localization

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 a CSV containing your localizations; 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 a data-ua-id="new-users" attribute by placing a new-users column in your CSV.

By default, Airship treats elements with data-ua-id attributes 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 <br> elements.
  • 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 attribute 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 src attribute.
  • data-ua-video — Airship will insert a <video> tag in the parent element using the translated value as the video's src attribute. The video tag also includes a controls attribute.

Formatting the Localization CSV

When localizing a custom HTML message, you will upload a CSV file containing translations for each language and country combination that you want to localize your message for. Your localization CSV must represent the HTML elements that you populate with localized text or values. The first row contains your column headers, and each subsequent row in the CSV represents a different localization, broken down by language and country code.

Your CSV must contain:

  • id.language and id.country column headers.
  • additional column headers corresponding to data-ua-id attributes for the custom HTML elements that you want to localize.
  • a row with empty id.language and id.country values; this row represents the default localization for the message and is issued to users who do not match any of the language/country combinations in your CSV.
 Tip

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 locale in the Audience step. This will ensure that your message only goes to users with the locales specified in your CSV.

Column headers and values:

  • 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 .key is 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.
  • key — CSV headers associated with HTML (data-ua-id) attributes. The header is the value of a data-ua-id attribute associated with a custom HTML element, and the value is the localized information you want to pass to that element.

Localization Actions

You can assign an action to any element in your custom HTML that has a data-ua-link attribute. You can assign these actions directly through your CSV, by adding a column in your CSV with a 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 data-ua-id of flooble.

You must set your actions in your localized CSV. You will not be able to set actions in the composer workflow.

  • 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_rating is not "true".
  • app_rating.body - Sets body of App Rating modal; this key is optional and ignored if app_rating is not "true".

Send a Localized Message

To take advantage of localization, you will create a custom HTML In-App Automation. Before you begin, you should have your formatted custom HTML message with data-ua-id attributes representing the parts of your message you want to localize. You may want to have the CSV file containing your localizations ready, though you can generate a sample CSV file with all the headers you need to populate for your Custom HTML file as a part of this process.

  1. Open your messaging project, then click Create and select In-App Automation.
  2. Select the Custom HTML message style, then click   to continue.
  3. Configure the message settings, then click   to continue.
    • Enter a message name.
    • Enable any additional Options.
    • Enable Localize this message for multiple languages.
    • You can also flag the message as a test if you want to test your localizations and custom HTML before you send to a live audience.
  4. Select your audience, then click   to continue.
    • All Users: Sends the message to your entire audience.
    • Test Users: Predefined recipient groups. After choosing Test Users, select from the Test Groups dropdown menu that appears. See: Test Groups.
    • Target Specific Users: Create a recipient group based on available conditions. See: Target Specific Users: In-App Automation.
  5. For Custom HTML, click Choose File and select your HTML file.
  6. For Localization, 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.
     Tip

    If you have not already created your localized CSV, click Get sample CSV file to download a CSV file containing columns for each element associated with a data-ua-id attribute that you need to localize.

    If necessary, you can click Exit and complete your draft when you've finished populating your localization CSV.

  7. Click Create localized HTML to generate a preview of the HTML. Use the dropdown menu to review your localizations. Click   to continue.
  8. (Optional) Set a tag when the message is displayed.
     Tip

    Set a tag in conjunction with tag-based targeting to prevent members of your audience from seeing a message multiple times, or to chain messages together. E.g., set a tag “message1” on display of one message, and only display a second message to users who have the “message1” tag.

  9. (Optional) Override the default design settings for your custom HTML message. Changes apply to the current message only and do not affect the project's default design settings.
  10. Configure the trigger events that will cause the message to appear to users and click   to continue. You can also set conditional options that cause the message to display when triggers occur and the condition is true. See Display Triggers for information.
  11. Review your message and click Finish. If you want to make changes, click EDIT, make your changes, and return to the Review step. If you exit before you send the message, the message is saved as a draft and not yet active.