Set up user language and locale

Decide which signal determines the language a consumer receives, then set that value on the user profile so localized campaigns and Canvases target the right audience.

About this example

UponVoyage, a fictional travel brand, personalizes messages for consumers across twelve markets. Marketing derives language from a market custom attribute set to the country a consumer books outbound travel from. That attribute maps to a region rather than a language, so consumers who book from a multilingual country—or from a country outside their own—can receive the wrong language.

This example compares three signals for a consumer’s language and shows how to set each one on the profile:

• SDK-collected language: The language standard attribute, captured from the device or browser locale
• Explicit language preference: A value the consumer chooses in your app or on your site, set through the SDK or REST API
• Market or region custom attribute: A business attribute such as market, used when your content varies by region rather than by language

language and country are separate standard attributes in Braze. When regional variants matter (for example, European Spanish compared to Latin American Spanish), target both attributes rather than storing a combined locale string.

This example shows how to choose a language signal and set it on the profile. For storing and sending translated copy, see Compare translation approaches.

Considerations

• Country comes from IP geolocation first. Braze identifies country by IP address geolocation. If geolocation isn’t available, Braze identifies country by the device locale. Don’t treat country as a device-reported value. For more information, see SDK data collection.
• Language collection is optional and can be turned off. language is optional data collected by default, so a minimum integration or a device property allowlist can exclude it. Confirm your integration still collects it before you rely on it. For more information, see Storage.
• Most recent device locale may be absent. Not every consumer has a value, so plan a fallback language for messages that use it.
• Setting a value explicitly stops automatic collection. After you set language or country through the SDK, REST API, or CSV import, Braze stops automatically updating that field for that consumer. Plan for how a consumer changes their preference later.
• Explicit values consume data points. SDK and API attribute updates log data points, while automatic collection doesn’t. For more information, see Data points.
• language must be an ISO 639-1 code. Use two-letter codes such as en or nl. For the supported set, see Language codes. country uses ISO 3166-1 alpha-2 codes such as GB or BE.
• Changing your language model affects existing assets. When you move from a custom attribute to standard attributes, audit the campaigns, Canvases, segments, and Liquid that reference the old attribute before you retire it.

Setup

Step 1: Choose the signal that determines language

Where you can collect an explicit preference, use it as your primary signal and fall back to SDK-collected language. A market attribute is a poor substitute to infer language in multilingual countries such as Belgium, Canada, and Switzerland.

Step 2: Confirm what your integration already collects

1. Go to Audience > User Search, open a consumer profile, and check the Language and Country fields.
2. If Language is empty across profiles, confirm your SDK integration doesn’t exclude it from device property collection.
3. Note whether Most Recent Device Locale is populated. Use it for diagnostics, and don’t target on it without a fallback.

Step 3: Set an explicit language preference

Use this step only when you chose an explicit language preference in Step 1. For SDK-collected language, confirm collection in Step 2 and skip to targeting. For a market or region custom attribute, set that attribute through the SDK or REST API, then continue with Steps 4 through 6 as needed.

When a consumer chooses a language, send that choice to Braze so it takes precedence over automatic collection.

Set the value through the SDK when the choice happens in your app or on your site. For method names on each platform, see Setting user attributes.

For preferences stored in your own systems, send the standard attributes through the /users/track endpoint:

1
2
3
4
5
6
7
8
9

{
  "attributes": [
    {
      "external_id": "{YOUR_EXTERNAL_ID}",
      "language": "nl",
      "country": "BE"
    }
  ]
}

Replace YOUR_EXTERNAL_ID with the identifier for the consumer whose preference changed.

Step 4: Set country when a consumer signals a region

Set country explicitly when a consumer tells you their region—for example, when they browse a country-specific site or select a market at signup. Use the same /users/track request or SDK method as the previous step.

If you want IP-based country to keep updating, don’t set country explicitly. Choose one source per consumer and apply it consistently.

Step 5: Target messages on language and country

1. Build segments with the Language and Country filters rather than a combined locale attribute.
2. For messages that vary by region within a language, filter on both attributes—for example, language is es and country is ES.
3. To send one message that renders per locale, add locales using the default language and country attributes, then see Multi-language messages.
4. If you keep a market attribute for regional content, add a locale based on custom attributes instead of mapping that attribute to a language.

Step 6: Migrate away from a market-based language model

1. Search your workspace for campaigns, Canvases, segments, and Content Blocks that reference the market attribute.
2. Backfill language for existing profiles through CSV import or the API where you already know a consumer’s preference.
3. Update assets to filter on Language, keeping the market attribute only where content varies by region.
4. Confirm each locale renders as expected with Preview message as user before you retire the old attribute.

Related articles

• Standard attributes
• SDK data collection
• Language codes
• Setting user attributes
• User attributes object
• Localization settings
• Multi-language messages
• Compare translation approaches