This feature is available from the Pro plan and above.

Use this app to localize your Braze campaigns with Lokalise.

Index

Getting started

This integration is based on Braze’s connected content. On Braze, you will use connected content whenever you want a piece of content to be localized, including within content blocks. The connected content will be retrieved from a different dedicated URL for each language; therefore, your users should have language information tied to their profiles.

If you haven't already done so, open your Braze dashboard and proceed to Users > User import. Here you can import your users as explained in Braze documentation. When preparing a CSV file for importing, make sure to include a language column with users' languages. We will use this language field later when displaying translations. It’s very important that you use the same language codes as on Lokalise.

In Lokalise, you will create a translation key for each one of the connected content variables that you define in Braze. Once the translations are ready, you can generate one JSON file per language, and get it published on the URLs that will serve your connected content.

Preparing your translations on Lokalise

First of all, prepare your translations on Lokalise, on a software localisation project. You’ll need to create the translation keys manually, with the same name that you’re using on Braze connected content variables. For example, let's create a simple translation key description:

Known issues

  • Your keys must be assigned to the Web platform.

  • Please avoid using keys that contain periods . or the _on string. For instance, use this_is_the_key instead of this.is.the.key, and use join_us_instagram instead of join_us_on_instagram.

Configuring the Braze app on Lokalise

Open your project, and click Apps. Here search for the Braze app, click on it and then press Install.

You are going to see the following screen:

On the translation file URL, Lokalise publishes a JSON file containing all the translations for your keys in the project. You'll get as many translation file URLs as target languages you have in your project. This is why the resulting translation file URLs have two pieces:

  • The first part of the URL path is common to all languages.

  • The JSON file name at the end of the URL is based on the language code. Remember, it’s very important that you use exactly the same language codes on Lokalise and on Braze user profiles.

The translation file URL is the URL that you will need when configuring a Braze campaign. You can update the content on the JSON file by clicking Refresh; note that the URL will stay the same and you don't need to change your connected content call on Braze's side.

To test that this URL works correctly, just copy it, replace {{${language}}} with a language code (for example, en) and open this URL in your browser. You will see a JSON file with your keys and translations:

That's it!

Using translations in Braze campaign

When you are ready, return to Braze and proceed to Campaigns.

First, remember that the connected content will be retrieved from a different dedicated URL for each language; therefore, your users should have language information tied to their profiles.

Open an existing campaign or create a new one. For the purposes of this article, we'll create a new Email campaign with some sample content.

Click Edit Email Body:

You will see your email's HTML markup which utilizes Liquid template language.

In order to utilize your translations, you need to add the connected content request once in the HTML, either at the top of the document or right before the first place where a translation is needed. You do it by inserting the following markup:

{% connected_content https://exports.live.lokalise.cloud/braze/123abc/456xyz/{{${language}}}.json :save translations %}

Replace the https://exports.live.lokalise.cloud/... URL with the translation file URL fetched in the previous step.

  • {{${language}}} means "insert user language on this position". Alternatively, you can hardcode your language code, for example en.json.

    • Note: To ensure that the appropriate translated JSON file is retrieved for each user, you must place either the {{${language}}} profile attribute or another similar custom attribute that holds the user’s language at the end of the translation files URL. E.g., /{{${language}}}.json. The values held in these attributes must match the prefix of each of the translated JSON files. This will ensure the correct translation file is returned for each user.

  • :save translations is going to save the JSON content under translations variable.

Now simply use the translations variable to display the desired translations by their keys.

For example, to display the description key you would say:

{{ translations.description }}

Now simply save the email template and preview it. You should see your translation being displayed:

Frequently asked questions

  • What happens if I accidentally delete a key from Lokalise? The corresponding string on Braze won't have a translation anymore.

  • If I have an en locale but override it with en-US on Lokalise, will Braze read it as en-US? No, locale ISO codes must match on Braze and Lokalise.

  • Can we use the :rerender flag when connecting Lokalise content? Yes, sure. You can consult Braze docs to learn how to add this flag.

  • After refreshing the translation file on Lokalise, I can't see any changed on the translated content on Braze. Why? Braze caches translated content on their side, and it can take a few minutes to refresh. If you're testing your campaigns and you need to see the results of translations immediately, you can use the :cache_max_age parameter as explained in this article.

Did this answer your question?