.svg)
Braze campaign internationalisation is a data and governance problem before it is a translation problem. Locale lives on the user profile, translation tags mark the text, and translation files attach per campaign. Decide your locale keys and your fallback before the first message is built, because reworking them later means touching every campaign you have already shipped.
Key Takeaways
- Locale sits on the user profile, written by the SDK or the API, and surfaces in segmentation under Country and Language.
- When a user matches both a custom attribute locale and the default attributes, the custom attribute wins.
- Braze documents four orchestration approaches, and the choice is a reporting choice as much as a build choice.
- Keep the protocol and query parameters outside the translation tag, because translators can alter special characters and break the link.
- Deleting a custom attribute, or changing its type, silently drops users out of that locale with no error.
- Translation files attach at campaign level, so a correction is a per-campaign action unless the copy sits in a Content Block.
How does Braze decide which language a user sees?
Locale sits on the user profile. Braze documents that locale information is stored there from data an SDK collects automatically, or from the API. It carries a language and a region identifier. It surfaces in segmentation under Country and Language.
That single sentence sets the order of work. Nothing downstream can be correct if the profile attribute feeding it is wrong, missing or inconsistently cased across your sources. Locale is an ingestion concern that happens to have a messaging symptom.
There is a second path. A locale can be defined from custom attributes rather than the default language and country attributes. Braze states that when a user matches both, the custom attribute locale wins. Write that rule down. It decides which definition applies.
How do you plan a Braze campaign internationalisation rollout?
Sequence matters more than tooling here. Each step below produces something the next step depends on, and each one is cheap now and expensive after launch.
- Audit the locale attribute at source. Confirm what the SDK and the API are actually writing, including casing and region suffixes, before anyone opens a campaign.
- Agree the locale key naming convention and write it down. Braze does not impose a format and says you can use your preferred naming convention.
- Create the locales in workspace settings, and decide per locale whether it is driven by default attributes or custom attributes.
- Agree the fallback text and the rule that produces it, before any translation exists.
- Build one message end to end in one non-English locale, including a link and a tracked link, and send a test.
- Only then scale to the remaining markets.
Step five is the one teams skip. One message carried all the way through preview surfaces the link, tracking and attribute problems described below. The blast radius is one campaign, not the whole programme.
Which orchestration approach should you choose?
Braze documents four approaches: one template for all, one template per country, one journey for all, and one journey per country. The choice is a reporting choice as much as a build choice.
| Approach | Reporting you get | Choose it when |
|---|---|---|
| One template for all | Aggregated metrics, country split needs custom segment funnels | Content is identical across markets apart from language |
| One template per country | Per-country sending analytics in the dashboard | Offers, pricing or legal copy differ by market |
| One journey for all | Aggregated Canvas analytics | Journey logic is shared and only copy varies |
| One journey per country | Per-country analytics, including per step and variant | Timing, channel mix or journey shape differ by market |
Braze names the considerations for the centralised options plainly: manual report building, aggregated rather than per-country metrics, and scheduling across time zones being harder. Those are the costs you are accepting when you pick one template for everything.
The recommended way to put language into a single message is the translation Liquid tag, which wraps text with a tag identifier. Multi-language translations reached general availability in the release of 30 April 2026, so this is the current path rather than an early access one.
What breaks when translation tags meet URLs?
Links are where localised messages fail in production without warning. The failure is rarely visible in the editor. Braze is specific about the handling.
Keep the protocol outside the translation tag and wrap only the domain and path. Braze gives the reason directly: translators may alter or remove special characters, which breaks the link. Query parameters stay outside the tag for the same reason.
Email link tracking needs one more step. Braze adds tracking parameters to each URL. When a URL sits inside translation tags, it may not work out where to put them. The documented fix is a trailing character after the closing tag. Use a question mark when the URL has none, and an ampersand when it already carries one.
The same discipline applies to markup. Only human-readable text belongs inside a translation tag, and Braze warns against wrapping attributes such as class, style or identifier values. Tags cannot be nested either.
Where do locale keys go wrong?
Two documented behaviours deserve a place in your runbook, because both fail silently.
Braze states that if a custom attribute is deleted, or its type changed, the user can no longer fall into that locale. They move down the priority list, or receive the default marketing translations. Nobody gets an error. Somebody in that market simply gets English.
Content Blocks behave the same way. Braze states that a Content Block missing translations for one of your added locales shows in its original language for users in that locale. A partly translated message is a realistic outcome, not an edge case.
That is why the fallback text is a design decision, not a leftover. Braze recommends always including a fallback statement. It names who receives it: users with no language set, users whose language is unsupported, and users whose device language cannot be detected.
What should you check before adding a locale?
Some limits and behaviours are worth knowing before the build rather than during it.
| What | Documented behaviour |
|---|---|
| Locales per workspace | Up to 200 |
| Attributes per locale | Up to two custom attributes, or up to two default language attributes, second optional |
| Translation tags per message | Up to 200 |
| Default text per tag | Up to 2,000 characters |
| Translations per locale | Up to 409,600 bytes, roughly 409.6 KB |
| Where translation files live | At campaign level, so each message variant needs its own uploaded translations |
| Who supplies translations | You do, by file upload or the translation API |
| Duplication | Translations travel with a duplicated campaign, Canvas step or variation, and across workspaces when the locales exist at the destination |
The per-campaign storage row is the one that shapes operations. Because files attach to the campaign, a translation correction is a per-campaign action unless the text lives in a Content Block. Putting recurring copy such as footers and legal text into Content Blocks turns one correction into one edit rather than many.
Braze also publishes a validation table covering upload and download failures. A file carrying locales that are not on the message will not upload. A file whose default text no longer matches the message will add translations while leaving the original text alone, which is the quietest failure of the set.
As a Braze implementation partner, the rule we put in a client runbook is short. Treat locale keys as a schema. Version them. Never rename one in a live workspace without first checking every campaign that references it.
Frequently Asked Questions
1. Does Braze translate the copy for me?
Braze states that you supply your own translations. Upload a file, or use the translation API.
2. How many locales can one workspace have?
Up to 200, per the localisation settings documentation.
3. Can I change translated copy after a campaign is built?
Edit the file and upload it again, or use the translation API update endpoints.
4. What happens to a user whose language is not covered?
They receive the fallback content, which is why Braze recommends always including a fallback statement in the message.
5. Do translations survive duplicating a campaign?
They do. Braze documents that translations are included when you duplicate a campaign, Canvas step or variation, and when copying across workspaces if the locales exist there.
Sources
- Braze, Localization. Retrieved 11 Sep 2026.
- Braze, Localization settings. Retrieved 11 Sep 2026.
- Braze, Multi-language messages. Retrieved 11 Sep 2026.
- Braze, Release notes, 30 April 2026. Retrieved 25 Sep 2026.
Related reading on this site: hyper-personalisation in Braze campaigns, dynamic content delivery, onboarding journeys in Canvas, onboarding campaigns that lift activation, retention strategies using Braze.
CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.
If you are standing up a second market and the locale keys are not agreed yet, let's talk.
.svg)
