How to generate a first-class resource file: usage of variables in strings

I’ve been revisiting our How to generate a first-class resource file series, and realized we missed one key piece, one of the most common and problematic scenarios when delivering localized content: broken strings caused by poorly handled variables.

This issue usually shows up when the UI displays placeholder code or incorrect values. Not only does this leave users without essential information, but if the content is highly visible, it can lead to media backlash or even legal implications.

This typically happens for two reasons:

1. Engineers didn’t fully communicate their needs to the internationalization (I18n) team when the project was set up.
2. A new engineer joined the team and didn’t go through proper i18n onboarding.

But in both cases, the root cause is the same: lack of coordination on how variables should be handled between engineering and i18n teams.

Let’s say an engineer needs to display this in the UI:

Hello John! Your payment of $100 has been properly processed.

They’ll need to break the string down into static text (translatable) and dynamic values (variables). In this case, John¹ and $100² will vary, while the rest remains the same.

The engineer might define it like this:

Hello <first_name>! Your payment of <amount> has been properly processed.

When translated into Spanish, the variables must remain untouched:

Hola <first_name>. Tu pago de <amount> se ha procesado correctamente.

Why? Because the code looks for those exact variables to replace with dynamic values. If the linguist delivers this instead:

Hola <nombre>. Tu pago de <cantidad> se ha procesado correctamente.

Then those variables won’t resolve in the UI. You’ll end up displaying exactly what’s written (brackets and all).

To prevent this, CAT tools let us lock variables so linguists can’t modify them. But that brings another risk: if your variable syntax uses common punctuation (like angle brackets), it might block legitimate terms from being localized.

Imagine this situation where File and Print are menu label items within the UI:

Click <File> and select <Print>.

If angle brackets are treated as protected syntax, the translated string will become:

Haz clic en <File> y selecciona <Print>.

Which is clearly not ideal, especially if the UI has been already localized or will be in the future.

That’s why it’s critical for engineering, UX writing, and i18n teams to align on variable formatting early. Common formats include:

• {first_name}
• ${first_name}
• {{first_name}}
• %s

The best ones are descriptive, giving linguists context on what kind of value will appear (a name, a number, a date, etc.). If you just use %s or %d, that’s fine for engineers, but often not helpful enough for a translator to make the right linguistic choices. For that reason, this is the least favorable one as it provides no additional clue on what the variable value is going to be.

So if you’re an engineer unsure about how to format your variables: don’t wing it. Ask your i18n or localization team. There’s no need to reinvent the wheel, and doing so could create more problems than it solves.

Thanks for reading! I hope this helped clarify how variables should be defined and used in global-ready code.

See you in our next post!

1. Be mindful when using names in strings. As we discussed in a previous post, handling names can be surprisingly complex and should always be coordinated with your i18n or globalization team. ↩︎
2. Currencies vary across regions. Not just the symbol, but also the format. It’s important to plan your strings accordingly and align with existing localization practices to ensure correct display in every market. ↩︎