nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

What catalog structures have you tried? What were the pros and cons?

marinavogtlvh

Hey,

we're looking at using catalogs to manage multi-lingual content, and I'm wondering: What's the optimal catalog structure? A catalog per message, per canvas, per language, or content type? What have you tried and what were the pros and cons? What did you wish you knew before you started using catalogs?

Find more posts tagged with

Catalogs

Accepted answers

jerome_ahkan

@marinavogtlvh hey Marina! we don't currently use catalogs for multilingual content, but catalogs have become a core part of how we manage promotions at scale.

Our setup is centered around promotional content rather than language. We use them to dynamically serve different content across multiple codes and offers as well as value, message copy and headers across our different customer cohorts. This gives us a lot of flexibility without needing to duplicate campaigns or hardcode content into campaigns or canvases.

Some of the benefits we've seen are:

Ability to update offer details without touching campaigns
Easier cohort-specific personalisation
Reduced campaign duplication

One thing we've learned is to structure catalogs around what you're trying to manage (in our case, promotions) rather than around the channel or campaign 😊

All comments

jerome_ahkan

@marinavogtlvh hey Marina! we don't currently use catalogs for multilingual content, but catalogs have become a core part of how we manage promotions at scale.

Some of the benefits we've seen are:

Ability to update offer details without touching campaigns
Easier cohort-specific personalisation
Reduced campaign duplication

One thing we've learned is to structure catalogs around what you're trying to manage (in our case, promotions) rather than around the channel or campaign 😊

Nirnay

This is something I've been wanting to share for a while. There are so many questions floating around the different Braze Slack groups and here on Bonfire about how people manage
translations, and honestly the implementations differ a lot because there's no single right answer. So I'm not going to pretend this is the way. It's just what we landed on, and
why.

The headline is that we kept it very modular.

Every piece (the gate, the handler, the resolvers, each copy catalog) is its own swappable unit, so we could retrofit i18n onto a large existing email program without rewriting it, and roll it out in phases.

The context that shaped everything

We operate in around 30 countries, and we had 200+ emails already live with zero i18n logic baked in. So retrofitting translation had to be a phased rollout on two axes at once.
Phased by email (migrate them in batches), and phased by language (we shipped German first, then French, with more to come). We couldn't flip a switch and hope every email in
every language was ready on day one. That constraint shaped the whole catalog design, so let me start where we started: the gate.

It started with the gate

The first catalog we built wasn't copy at all. It was a switch table, i18n_switch. The id is the locale, enabled turns the whole locale on or off, and there's one column per
email named to match the campaign.

id	enabled	welcome_email	booking_confirmation	abandoned_cart
en-AU	true	true	true	true
de-DE	true	true	true	false
fr-FR	true	false	true	false
es-ES	false	true	true	true

How to read each row:

en-AU is the base locale, everything on.
de-DE is live, and switched on for welcome and confirmation, but the abandoned-cart copy isn't ready, so German users fall back to en-AU for that one email only.
fr-FR is live, but only the confirmation email has been migrated so far.
es-ES is switched off entirely, so it doesn't matter what the per-email columns say, every render falls back to en-AU.

The rule: active_lang is the user's locale only if enabled == true and the column matching the campaign name is true, otherwise en-AU. Translation is off by default. (The column
name has to match whatever {{campaign.${name}}} returns for that send, so name each column after your own campaign naming convention.)

That one table gives us both phasing axes with zero code deploys. Add a column to roll an email out across languages, flip a locale's enabled to launch a new language (German
first, then French), or pin any single cell off while its copy is in progress. With 200+ emails to migrate, that gradual control was non-negotiable.

The handler is the one brain

The switch table is just data. The thing that reads it is a single content block, util__i18n_handler, and it's deliberately the only place that decides what language a render is
in.

It does three things, in order:

Reads the user's preferred_language custom attribute, defaulting to en-AU if it's blank.
Looks up that locale's row in i18n_switch and applies the gate: active_lang becomes the user's locale only if enabled is true and the column matching the campaign name is
true, otherwise it falls back to en-AU.
Honours a manual over_write_active_lang override if one is set, which is our escape hatch for testing a locale without touching the user's attribute or the switch table.

Its only output is one variable, active_lang. Every copy catalog lookup downstream just trusts that value and reads its own row for that locale. That's the whole point of keeping
it separate. The gate logic lives in exactly one block, so if we change how rollout works (say we add a region check, or a date-based launch), we change it once and every email
and every catalog inherits it. No gate logic is ever duplicated into a template.

One thing to watch: because the subject line, preheader, and body are separate Liquid renders, the handler has to run once in each of them before any t_* variable is used. So the
call order in every render context is always the same. Run the handler to get active_lang, then run the relevant lookup block to fill the t_* variables, then reference them.

Then: locale is the row, not the catalog

Once the gate and handler existed, the question was how to shape the copy catalogs. The thing that actually works, after we tried and abandoned catalog-per-language, is
locale-as-row. The locale is the item ID, and each translatable string is a column. So the answer for you @marinavogtlvh here is (A catalog per message)

id (locale)	t_subject_line	t_preheader
en-AU	Welcome aboard	Now you can experience more...
de-DE	Willkommen an Bord	Jetzt können Sie mehr erleben...
fr-FR	Bienvenue à bord	...

A lookup block resolves the user's active_lang to a row and pulls every column into t_* variables, and the email just references {{ t_subject_line }}.

The payoff is two-fold. For ops, adding a language is one new row, not N cloned catalogs and rewired lookups, and translators see English plus every locale side by side. At send
time, it's a single catalog lookup per user (one row keyed by their language) instead of fanning out across multiple language catalogs.

One-click translation for marketers

Because every catalog has the same shape (an English row plus one row per locale), we built a small translation API on top of it. You point it at a catalog name, it reads the
en-AU row, finds all the language rows that exist, and translates the English content into each locale in one click. Marketers don't touch Liquid or hand strings to a translation vendor. They fill in English, hit translate, and QA the result.

The one thing we had to get right there was personalisation tags. The API ignores anything wrapped in { ... } or ${ ... }, so it won't translate token contents and things like
{{${first_name}}} and {% if ... %} survive untouched. On the Liquid side we :rerender on the catalog read so those tokens still personalise normally at send time. Get either half
wrong and you either ship a "translated" broken tag, or a literal unrendered token in the inbox.

Modular catalogs, split by scope and change cadence

This is where the modularity really pays off. One mega-catalog hits column limits and mixes ownership, so we split by how widely content is reused and how often it changes. Each
catalog is paired with its own resolver content block:

i18n_switch is the gate above
i18n_header and i18n_footer are shared chrome, used in every email, change rarely
i18n_generic_components and i18n_offer_design are reused component families
i18n_email_<name> is copy unique to one email, changes per campaign

Because each catalog has a matching lookup block, an email only pulls in the pieces it actually uses, and we can change one without touching the others.

……….(continued in the next comment)

Nirnay

Two things that make or break this

Keep the resolution logic in exactly one place. It's tempting early on to inline a bit of "if German then..." into a template, and it always
costs you later when the rollout rules change. Funnelling every render through one handler and one lookup-per-catalog is the single thing that
made a phased rollout manageable across 200+ emails. The day we needed to change how the gate works, we changed one block and every email
inherited it.

Treat observability as part of the system, not an afterthought. We send all of these checks to Datadog, so if translation data isn't available
for a given locale and email at send time, we hear about it before a customer does. With translation off by default and a fallback to en-AU,
the failure mode is silent by design, so the alerting is what actually tells you a locale or an email has a gap. That safety net is what let us
roll out aggressively without worrying about quietly shipping the wrong language.

Net: start with a gate so you can phase rollout by email and by language, run it through one handler so the logic lives in a single place, make
language the row (one call per user, one row per language), keep every catalog the same shape so a translation API can fill it in one click,
and stay modular so each piece stays swappable. Happy to share the resolver Liquid if anyone wants it.

marinavogtlvh

Hi @Nirnay thanks for the detailed response, that was a really interesting read. Hope you have time for a some follow up questions.

If you're using a catalog that presumable houses all content across languages, why did you feel the need to migrate language by language? Did that not mean you have to retroactively update catalogs, instead of making use of the copy you already have on day 1?

I tried using :rerender however it didn't work for me, so I switched to replace and that seems to work on light testing. Did you try replace, and if so, why did you decide against it.

I saw your other thread too about assigning variables, so I'll keep an eye out for that too. For now, I've just done a simple sheet like so:

id	subject_line	preheader	para1
en	hello	lorem	ipsum
de	hallo	lorem	ipsum

and in each email I just reference the column in the right place. Do you think that's scalable and easily managed across a few hundred assets with catalog per campaign/canvas?

Nirnay

Hey @marinavogtlvh, great questions, happy to go deeper.

On migrating language by language :

The catalog structure supports all languages from day one, you're right. The phasing wasn't about the catalog shape, it was about confidence in the output. We built a translation API that reads the English row and generates all the language rows automatically, so the catalog is never sitting empty waiting on a translator. The phasing was more about QA and following our website's rollout approach, so whichever market went live on the website first got prioritised for email too. The gate meant we could flip a language on across a batch of emails the moment we were happy with the output, without touching any templates.

On :rerender vs replace

We did try replace early on and it works for simple cases, but we moved away from it because it's brittle. The core problem is that replace is a dumb string substitution with no awareness of Liquid or Braze syntax. So if a translator accidentally adds a space, changes casing, or touches anything inside a token, the substitution silently fails and you ship the raw placeholder. It also can't handle conditional logic inside catalog values at all, so anything beyond a flat string becomes a workaround on top of a workaround. And if you ever need to personalise copy, you're stuck because replace has no way to resolve user profile fields.

:rerender is the Braze-native way and it actually evaluates the Liquid inside the catalog value at send time. Take your catalog as an example. Say you want to personalise the subject line with first name:

id	subject_line	preheader	para1
en	Hello {{${first_name}}}	lorem	ipsum
de	Hallo{{${first_name}}}	lorem	ipsum

With :rerender Braze evaluates {{${first_name}}} inside the catalog value at send time, so the user gets Hello Jane rather than the literal string Hello {{${first_name}}}. One important catch is that if your catalog value contains a user profile field like {{${first_name}}}, that value must be defined in Liquid earlier in the message before the catalog read, otherwise Braze won't have the context to resolve it.

:rerender also works on content block references, so {{content_blocks.${test}}} inside a catalog value will resolve properly too. If :rerender isn't provided at all, Braze just renders the raw Liquid string as-is without evaluating anything. If it didn't work for you it might be worth checking whether the catalog field type is set to text rather than something else, that caught us out early.

On your catalog-per-email structure and why variables from other thread :

To clarify what I meant, using your table as an example, right now every email that uses this catalog probably does something like this inline:

{% catalog_items email_copy en %}

{{ items[0].subject_line }}

{{ items[0].preheader }}

{{ items[0].para1 }}

That's fine for one email. But the real value at scale comes from wrapping that in a dedicated lookup content block, say util__copy_lookup , which does all the catalog read and assigns the values to named
variables:

{% catalog_items email_copy en %}

{% assign subject_line = items[0].subject_line %}

{% assign preheader = items[0].preheader %}

{% assign para1 = items[0].para1 %}

{% assign para2 = items[0].para2 %}

{% assign header1 = items[0].header1 %}

Every email then just calls {{content_blocks.${util__copy_lookup}}} and references {{ subject_line }}, {{ preheader }}, {{ para1 }}, {{para2}}, {{header1}} directly. The reason that matters is say you add a new column to the catalog, rename one, or change how the language resolution works. With a lookup block you make that change in one place and every email that includes the block picks it up automatically. Without it you're touching every email individually, and across a few hundred assets that's a significant difference, one edit vs. hundreds with plenty of room for inconsistency to creep in.

Hope this helps! 🙌