In-App Automation Localization Tutorial

Localizing your messages helps you reach your audience with content specific to their language settings without creating independent messages for each language.

In-App Automation supports localization for all message styles. Instead of creating individual messages for different locales The combination of a language and country. A user's locale is determined by their device settings. , you can create a single message and provide variations for each language you want to reach your audience in. Airship sends the appropriate localization to each member of your audience based on device settings gathered by the Airship SDK.

When you compose a message that you want to localize, you will upload a CSV containing your language variants. When Airship receives your upload, it automatically creates a localized message for each language or locale. You can then preview and edit each localized message in the In-App Automation composer.

 Tip

For your convenience, Airship provides a sample CSV for download in the Content step when creating your message. When you upload custom HTML, the sample CSV file contains columns for data-ua-id-associated elements in your custom HTML.

Formatting the Localization CSV

Your localization CSV file will contain translations for each language and country combination that you want to localize your message for. 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. Remember to leave 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. The only required value in a localization CSV is id.language, for all rows except the default localization row.

See: Localization CSV Format.

Send a Localized Message

Before you begin, you may want to have the CSV file containing your localizations ready, though you can download a sample CSV file as a part of this process.

The message content and settings you define in your CSV will appear preconfigured as you compose your message. Further editing of the content and settings is optional.

  1. Open your messaging project, then click Create and select In-App Automation.
  2. Select a message style, then click to continue.
     Note

    For Custom HTML, follow the steps in the Custom HTML localization tutorial on this page.

  3. Select the message layout, then click to continue. Layout options vary by message style.
  4. Configure the message settings, then click to continue.
  5. 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.
  6. Click Choose File and select the CSV file containing your localizations, then click Create Localized Message(s).
     Tip

    If you have not already created your localized CSV, click Download a sample CSV to download a CSV file containing columns for the data that you need to localize.

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

  7. Use the dropdown menu to review your localizations and edit the content as necessary, then click to continue. The preview updates as you type. Available fields and options vary per message style. Ensure the media URL will be accessible by your mobile audience. HTTPS is required. If your account has CDN enabled, you have the option to upload media rather than entering a URL. Contact Support if you are interested in enabling CDN media hosting.
  8. Assign an action for each button, then then click to continue. Select from the dropdown menu, then configure its settings.
    • Button Actions
    • (Optional) Set a tag when the button is pressed.
    • (Optional) Set a tag when the message is displayed.
       Tip

      Use this in conjunction with tag-based targeting to prevent a message from being seen or to chain the display of messages. 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. Toggle to enable Background, Text, or Buttons, and make your changes.
    • Changes apply to all localizations and cannot be applied only to specific localizations.
    • Changes apply to the current message only and do not affect the project's default design settings.
    • The available options are the same as those available when setting design defaults for your project in Settings » Configuration » In-App Automation.
  10. Configure the trigger events that will cause the message to appear to users, then 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 about each trigger and condition.
  11. Review the device preview and message summary, then click Finish. If want to make changes, click EDIT, make your changes, then either click or click the central navigation dot to return to the Review step. If you exit before this final step, the message is still a draft and not yet active.

Send a Localized Custom HTML Message

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. See: Formatting Custom HTML for Localization. You may also 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.
  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.

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 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 a data-ua-id="flooble" attribute by placing a flooble heading 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.

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 data-ua-id of 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_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".