Skip to main content

Fundamentals of building with Klaviyo

Course overview
Lesson
3 min read

Build international customer experiences with locale data

Bella's sent its new Berlin guests a welcome email in English, even though the flow set their locale to German. In today's global marketplace, it can be complicated to make sure you're speaking to each guest in their preferred language, location, and currency without relying on complicated flow branches and multiple email templates. By the end of this lesson, you'll be able to design a strategy that keeps guests' language preferences consistent as information moves between systems.

Meet Bella's

Bella's is an upscale French restaurant with locations across Europe, Asia, and the Americas. Each restaurant offers an experience shaped by local culture and guest preferences.

To promote its new Berlin location, Bella's ran a social media lead generation ad. The team wanted new leads to receive a welcome email in German, so they built a flow to set their locale to de-DE. The flow appeared to run successfully, but the messages sent to new guests' profiles still showed English.

The team discovered that an integration with its restaurant platform was overwriting the locale value. Now, the Developer team at Bella's is in fix mode: how can we prevent this from happening in the future?

Where in the world are Bella's guests?

In today's global marketplace, it can be complicated to make sure you're speaking to each guest in their preferred language, location, and currency without relying on complicated flow branches and multiple email templates. By the end of this lesson, you'll be able to design a strategy that keeps guests' language preferences consistent as information moves between systems.

So, the email is in German, but why? Did the guest choose German for communications, or did they sign up for emails while they were in Germany, using a German IP address. OR did the guest log into a German VPN for their Germany based job while visiting their aunt in France?

There's no perfect way to know which locale your guests prefer. But you can get close. Here are the data points you can collect to read the signals of how your guests want to be spoken to.

Ask the guest

Let the guest choose the language they want to receive. Klaviyo sign-up forms can collect that preference as a profile property. Bella's rule: use the same field and values across forms to prevent duplicate fields and mismatched values.

Two men working on laptops at a wooden table in a sunlit kitchen apartment.

Infer it from the sign-up page

Klaviyo can estimate a profile's location from an IP address when one is available, such as when someone signs up through a Klaviyo form. Some profiles won't have a location, and an IP-based estimate isn't always accurate. Learn more about how Klaviyo assigns profile locations.

A bearded man in a blazer works on a laptop at a desk in an office with bookshelves in the background.

Use an existing value

For imported or platform-supplied data, first check what the value means: a guest's language, a selected market, or a platform default? Shopify's locale syncs to Klaviyo's native $locale. Check what that value reflects. It can show the store's backend language instead of the language the guest was browsing in, and it may be empty if Shopify doesn't know it. A custom integration can update $locale through the Profiles API. Different sources can supply the data. They should not create different definitions of the guest's language.

Upscale restaurant dining room featuring tables dressed in white linens, muted green upholstered chairs and banquettes, herringbone-patterned wooden accent walls, and oversized drum pendant lights.

Hidden fields can overwrite an existing property when someone submits a form. Use them only when that behavior is intended. Review profile property and hidden-field behavior.

Build against your guests' home base

Now that Bella's is collecting guests' preferred language, considering location clues, and checking downstream updates from its other tooling, the team is working on how it can consistently collect and use that information.

Here are the steps Bella's took to make sure it has a consistent international messaging strategy.

Start by saving the locale preferences in one place

Klaviyo has a locale property on the profile that includes both region and language using the IETF BCP-47 tag (a standard code where the first part is the language and the second is the region, like de-DE for German in Germany or de-CH for Swiss German).

Bella's rule is to use native locale as the shared value for messaging instead of letting different systems use different language fields.

Decide when the language can change

Bella's custom integration needs to take the collected language information, turn it into a locale code, and save it using the Profiles API's Update Profile endpoint.

Other sources can also update Locale, which means that saving the Locale once does not mean the property will stay the same.

So Bella's had an architecture decision to make, with two cases:

  • When the guest has shared their preferred language, Bella's uses that answer, whether it was just collected or saved earlier and keeps it regardless of which IP address the guest uses in the future.
  • When the guest has not shared their preferred language, Bella's makes a tentative guess using clues such as IP-based location, site language, or the country where they booked a table.

These are Bella's rules for its integration, not an automatic Klaviyo priority order.

Under those rules, a software default or a new location clue must not replace a guest's stated choice, and Bella's checks the saved Locale after each connected system sends an update.

Keep booking details separate

Bella's collects reservation location on the reservation event, separately from the profile's messaging language.

In Bella's design, the team uses that booking information in its own message logic to share London-specific details, such as reservation prices in pounds rather than euros.

That does not mean Klaviyo automatically converts prices or changes Locale because someone booked in London.

Under Bella's rules, booking location can also be a language clue when no preference is known, but it does not replace a language the guest has already chosen.

Use smart translations

Smart Translations uses Locale by default to choose a message's language.

Bella's integration needs to save its chosen language value to Locale first; Smart Translations does not automatically read site language or reservation details to make that decision.

Smart Translations matches on language first. When Bella's Berlin welcome email goes to a guest whose Locale is de-DE, Smart Translations uses the German (de) translation, because Germany isn't a listed regional variant. Listed variants, such as Swiss German, can have their own version.

Smart Translations doesn't translate product data itself. If you use Shopify Markets, product blocks can show localized product information, currency, and pricing. Otherwise, catalog localization is a separate consideration.

Learn more on how you can customize content based on language.

Bella's rules come down to one question: did the guest choose this?

Update Locale: Changing the account preference to French for France, and asking for German for Switzerland, are both stated choices for future messages.

Keep the current Locale: The restaurant system's English default and a form submitted on an English-language page are signals, not choices. They shouldn't replace what the guest already told Bella's.

Record reservation context: A London booking and a Spanish-language menu describe one reservation. Save them with the reservation, not as the guest's language.

Check your understanding

Sort each new situation by the best next action, using Bella's rules above.
Future messages are requested in German for Switzerland.
Account preference changes to French for France.
Another form is submitted on an English-language page.
The restaurant system supplies its English default.
A Spanish-language menu is selected for one reservation.
Dinner is booked in London.
Update Locale
Keep the current Locale
Record reservation context
Build international customer experiences with locale data