DEV Community: Franco Ortiz

Why AI-translating your app quietly breaks placeholders (and how to validate it)

Franco Ortiz — Wed, 22 Jul 2026 17:07:49 +0000

The first time I AI-translated a locale file, it looked perfect. Every string had a Spanish version, the tone was right, nothing was missing. I shipped it. Two days later a user reported the app was printing Hola {nombre} on screen, literally, braces and all. The model had helpfully translated the variable name {name} into {nombre}, and now the interpolation didn't match any variable my code was passing.

That's the thing nobody tells you about using an LLM for translation. It doesn't just translate the words you want translated. It translates everything that looks like words, and a surprising amount of what's inside a locale string isn't text meant for humans.

What actually breaks

Locale strings are full of machine parts that have to survive translation byte-for-byte. An LLM sees them as language and rewrites them. A few real failure modes I've hit:

Variable names get localized. Welcome, {name} becomes Bienvenido, {nombre}. The braces are intact, the sentence reads fine, and the string is broken because your code injects name, not nombre. This one is nasty because it looks completely correct in review.

Plural syntax gets mangled. ICU messages like {count, plural, one {# item} other {# items}} are a mini-language. The model translates item and items (good) but also sometimes rewrites one/other into the target language or drops the #, and now the whole message fails to parse at runtime.

Inline markup gets dropped or translated. A string like Read our <link>privacy policy</link> comes back with <enlace> tags, or with the tags silently removed, or reordered so your React component can't match them.

Printf-style tokens vanish. %s uploaded %d files is easy for a model to "clean up" into something that reads better and passes zero arguments correctly.

None of these throw at translation time. They throw in production, in a language you probably don't read, for users who mostly won't file a bug and will just leave. It's the exact silent-degradation problem as locale drift, except now you introduced it yourself by trying to fix drift.

Level 1: tell the model what not to touch

The first defense is the prompt. If you're calling an LLM directly, be explicit and give it the variable syntax you actually use:

Translate the values to {targetLang}. Do NOT translate or modify anything
inside {curly braces}, %placeholders, or <tags>. Keep them exactly as-is,
in the same order. Return the same JSON structure.

This cuts the error rate a lot. It does not get you to zero. Models still slip, especially on longer strings, plural blocks, and anything where reordering the sentence "wants" to move a token. Prompting reduces the odds. It doesn't give you a guarantee, and locale correctness is a place where you want a guarantee.

Level 2: validate the output, don't trust it

The move that actually works is to stop trusting the model and verify its output mechanically. Extract every placeholder from the source string, extract every placeholder from the translation, and assert the two sets match. Different order is fine. Different set is a bug.

// pull out {name}, {{count}}, %{item}, %s, %d, <tag>...</tag>
const PLACEHOLDER = /\{\{?[^}]+\}?\}|%\{[^}]+\}|%[sd]|<\/?[^>]+>/g;

function placeholders(str) {
  return (str.match(PLACEHOLDER) ?? []).sort();
}

function validate(source, translated, key) {
  const a = placeholders(source);
  const b = placeholders(translated);
  if (JSON.stringify(a) !== JSON.stringify(b)) {
    throw new Error(
      `Placeholder mismatch in "${key}":\n  source:     ${a.join(" ")}\n  translated: ${b.join(" ")}`
    );
  }
}

That catches the {name} to {nombre} case, the dropped %s, and the missing <link>. For ICU plurals you want a real parser (@formatjs/icu-messageformat-parser) rather than a regex, so you can compare the message structure, arguments and plural categories, instead of just the tokens. But even the naive version above would have caught the bug that got me.

Run this over every translated key, fail loudly on mismatch, and the whole class of "the model quietly broke an interpolation" stops reaching production.

Level 3: put validation in the same step as translation

Level 2 works, but if translation and validation live in different places, someone eventually runs the translation without the check. So the real fix is to make them one operation: you can't get translated output that hasn't been validated, because validation is part of producing it.

This is what I ended up building into i1n. When it AI-translates a locale, placeholder and structure validation isn't a separate lint step you might forget, it runs on the output before anything gets written:

Translation happens with the variable syntax and product context baked in, so the model knows {name} is off-limits and that "Save" is a button, not a rescue.
Every translated value is checked against its source for placeholder parity and ICU structure. A broken interpolation never makes it into your files.
i1n check runs the same validation in CI, so even a hand-edited translation or a value from an external tool gets caught the same way.

The nice part is that validation and translation reinforce each other. The context makes the model wrong less often, and the check means the times it's still wrong don't cost you a production incident. You review a diff of correct-by-construction translations instead of auditing raw model output for landmines.

The short version

Prompting the model to leave placeholders alone helps, but it's odds, not a guarantee. Don't stop there.
Extract placeholders from source and translation and assert they match. This is the check that actually holds. Use a real ICU parser for plurals.
Make validation inseparable from translation so it can't be skipped, whether you wire that up yourself or let i1n do it (npx i1n init, free tier, no card).

Raw LLM output is a great first draft and a terrible last word. The models are good enough that the words will be fine. It's the parts that aren't words that will page you.

How to keep locale JSON files in sync (next-intl, i18next, or anything else)

Franco Ortiz — Tue, 21 Jul 2026 14:40:08 +0000

Every multi-language project I've worked on has the same bug. Not a bug in the code, a bug in the process: someone adds a string to en.json, ships the feature, and forgets that es.json, de.json and pt.json exist. Nothing fails. The build is green. Weeks later a user screenshots your app showing English text in the middle of a Spanish UI, and now it's a support ticket instead of a diff.

This happens with next-intl, i18next, vue-i18n, react-intl, all of them. The libraries solve rendering translations. None of them solve keeping the files in sync, because that's not a runtime problem. It's a workflow problem.

Why it keeps happening

The source locale is the only file that's ever up to date, because it's the one developers touch while building. Every other locale updates on a different schedule: when a translator gets around to it, when someone notices, or never.

The failure is silent by design. Most i18n libraries fall back to the key name or to the source language when a translation is missing. That's the right behavior in production (better English than a raw common.hero.title on screen), but it means the gap never throws. Missing translations don't crash. They just quietly degrade the product for everyone who doesn't read English.

And it compounds. Two languages, you can eyeball it. Seven languages and 900 keys, and no human can tell you which locales are complete without tooling.

Level 1: diff the keys

The minimum viable fix is a script that compares key sets between your source locale and everything else. Something like:

# keys present in en.json but missing from es.json
comm -23 \
  <(jq -r 'paths(scalars) | join(".")' locales/en.json | sort) \
  <(jq -r 'paths(scalars) | join(".")' locales/es.json | sort)

Run it before release and you at least know what's missing. Plenty of teams live here, and it's genuinely better than nothing.

The limits show up fast though. It tells you a key is missing but doesn't fill it. It doesn't catch a translation that exists but is stale because the English source changed. It doesn't validate that {name} survived into the German version. And someone has to remember to run it, which is the same failure mode we started with.

Level 2: put the check in CI

The single highest-leverage move: make locale drift fail the build. Missing key in pt.json? Red CI, PR blocked, fixed in the same change that introduced the string, by the person with the most context. The category of bug where "translations catch up eventually" just stops existing, because incomplete locales can't merge.

You can wire the diff script from level 1 into GitHub Actions in ten minutes. If you do only one thing from this post, do this. I've seen more i18n pain solved by one required CI step than by any library migration.

The catch: a blocking check is only tolerable if fixing the failure is cheap. If a missing Japanese string means "file a ticket and wait a week", people will disable the check by the second sprint. Which leads to level 3.

Level 3: close the loop with translation

The check tells you what's missing. The remaining question is who fills it in, and this is where most workflows stall, because the answer is usually "a spreadsheet, a translation agency, and a two-week round trip".

This is the part I ended up automating. I built i1n after hitting this exact wall at the fintech where I work (7 languages, locale files in the repo, translations perpetually behind). The workflow it settles into:

Strings stay in your locale JSON files, in your repo. No migration.
i1n push --translate diffs every locale against the source and AI-translates only the missing or changed keys, with product context attached so "Save" in a form doesn't come back as "Rescue".
i1n check runs in CI and fails on missing keys, broken placeholders, or coverage drops.
Native speakers review diffs instead of translating from scratch, which is the difference between a 10-minute review and a week of waiting.

The CI check has caught things nobody on the team could have: our Hindi locale drifted for a month once and no one noticed, because nobody on the team reads Hindi. The build noticed.

Whether you use i1n or build the pipeline yourself, the shape is the same: source locale as the contract, a diff against it as the check, and translation as an automated step instead of a queue. Get those three in place and locale drift stops being a recurring bug and becomes a build error you fix before merge.

The short version

Your locale files are already out of sync. Run a key diff today and find out how much.
Put that diff in CI as a required check. This is the 90% win.
Automate the fill-in so the check is cheap to satisfy, with AI translation plus human review, or with i1n doing that pipeline for you (npx i1n init, free tier, no card).

The drift never comes back once merging depends on it.

Our AI translation pipeline shipped __VAR_1__ to production in 7 languages

Franco Ortiz — Thu, 09 Jul 2026 13:59:05 +0000

A user opened our dashboard in Italian and the button said "Rigenera (VAR_1)". Not a variable. The literal text VAR_1, shipped to production, in seven languages, for weeks. Nobody noticed because we don't read Italian, or Japanese, or Hindi.

I build a localization tool. This bug was in my own product. That's the embarrassing part, and also why I think the postmortem is worth sharing: the failure mode applies to anyone piping strings through an LLM.

The setup
Our translation pipeline masks interpolation variables before sending text to the model. Regenerate ({wu} credits) becomes Regenerate (VAR_1 credits), the model translates around the token, and we swap the real variable back afterwards. Standard practice. The model can't mangle {wu} into {wu_créditos} if it never sees it.

Except we had two code paths into the translator. The direct one masked variables. The queued one, added later for batch jobs, didn't. And the prompt, shared by both, told the model "copy tokens like VAR_N through unchanged".

So for queued jobs the model received unmasked text with instructions about tokens that weren't there. Most of the time it translated fine. Sometimes it obeyed the prompt too literally and wrote VAR_1 into the translation, guessing where a token might belong. Valid JSON. Correct-looking diff. Straight into production.

Why nothing caught it
Every safety net we had was looking somewhere else:

The tests covered the masking function, which worked. The bug was that one path never called it.

TypeScript was happy. A string is a string.

The UI rendered fine. VAR_1 is just text, nothing crashes.

And the humans reviewed the English source, which was correct. The broken strings only existed in languages nobody on the team reads. That's the trap with i18n bugs: your ability to notice them is inversely proportional to how many languages you support.

What actually surfaced it
I wrote a check command for our CLI, mostly for CI: it diffs every locale against the source, validates that placeholders match, flags empty values. First time I ran it against our own projects it reported 47 broken strings across the landing page and the dashboard. I assumed the checker was wrong. It wasn't.

Fixing the data took an evening. Fixing the pipeline meant masking on both paths and adding a validation step that rejects any translation whose variables don't match the source, requeuing it with an error instead of shipping it quietly.

The check now runs in CI. A leaked token or a dropped placeholder fails the build the way a type error does, which is the only place this class of bug is catchable, because no human on the team was ever going to read the Hindi strings.

The takeaways
If you're doing AI translation, in any form:

Mask variables before the model sees them, on every path. Auditing that "every path" claim is the actual work.

Never trust the model's output structurally. Validate placeholders against the source after translation, and reject instead of shipping when they differ.

Treat locale files like compiled artifacts. Nobody proofreads a build output; you put a check in CI instead.

The check that caught this is part of i1n, the tool I work on (i1n.ai, CLI is open source). But honestly, even if you never touch it, write the placeholder diff yourself. It's an afternoon of work and it will eventually catch something a human can't, because it reads every language and your team doesn't.

Has anyone else had an LLM follow instructions too well? The model doing exactly what the prompt said, on input the prompt never anticipated, feels like a whole new bug category.

I mass-translated 200 keys into 5 languages. It went wrong in ways I didn't expect.

Franco Ortiz — Tue, 07 Apr 2026 19:36:29 +0000

Last project I had to internationalize an app with around 200 keys across 5 languages. I figured it would take a morning. It took most of a day, and the interesting part wasn't the translating. It was everything else.

The actual translations were fine. DeepL, Google Translate, whatever. Ten minutes. What killed me was the workflow around it:

Creating 5 copies of every JSON file. Keeping them in sync. Discovering that {name} got translated to {nombre} in the Spanish file and broke interpolation. Finding a typo (settigns.title) that rendered as blank in production because there's no runtime error for a missing key. Realizing a week later that I forgot three keys in Japanese entirely.

The thing that surprised me was the ratio. The translation itself was maybe 10% of the time. The other 90% was file management, variable protection, and chasing silent failures.

What silent failures actually look like

This is the part nobody talks about. Your app doesn't crash when a translation key is wrong. It just renders nothing. Or it renders common.header.subtitl as literal text. Or it works in English and Spanish but breaks in Japanese because you have {count} items and the variable got mangled.

You don't catch these in development because you're developing in English. They show up in production, reported by users who don't speak English, often weeks later.

How I stopped doing it manually

I built i1n to automate the parts that kept breaking. The whole workflow now:

i1n push --translate es,fr,de,ja,pt

One command. Variables stay untouched in every language. And it generates a .d.ts file, so if I typo a key, TypeScript catches it before I even run the app.

But the real shift was adding an MCP server. If you use Cursor or Claude Code, you can tell your agent "internationalize this component" and it extracts the strings, translates, and rewrites the code. I was skeptical about this one. For repetitive extraction work, it's genuinely good.

The 85% problem

AI translation isn't perfect though. It gets context wrong on short strings ("Save" as a verb vs "Save" as a noun), goes too literal on idioms, and sometimes loses tone completely. I've seen it translate "Drop us a line" as the equivalent of "drop a rope" in Japanese.

That's why I ended up building a dashboard too. The AI handles the first pass, you review what it generated, fix what needs fixing, and mark those as approved so they don't get overwritten next time. If your source text changes later, the system flags which translations went stale.

85% automation, 15% human review. That split turned a full day of work into maybe 20 minutes.

What I'd tell someone setting up i18n today

Don't start with the translation. Start with the workflow. Figure out how you're going to keep files in sync, how you'll catch missing keys before production, and how you'll handle variables across languages. The translation is the easy part.

The CLI and dashboard are open source (MIT) if you want to try it: i1n.ai

How are you handling translations? I keep running into teams that either set up a full TMS they barely use, or just skip internationalization entirely because the workflow is too painful.

I told my AI agent "internationalize this" and it actually did it

Franco Ortiz — Tue, 31 Mar 2026 13:37:36 +0000

I've set up i18n in Next.js App Router projects more times than I'd like to admit. It's always the same: middleware config, a pile of JSON files, wiring up the provider, copy-pasting keys between locales, discovering at 11pm that common.heor.title returns undefined in production.

The last time it happened I was mass-translating 40+ keys across 5 languages by hand. I stopped halfway through and thought: why am I still doing this manually?

So I built i1n, an open source CLI (MIT) that pushes your translation keys and gets them back translated with full TypeScript types. Free tier, no credit card, no 14-day trial tricks.

Let me walk you through the setup.

Prerequisites

A Next.js project (App Router or Pages Router)
Node.js 18+
~5 minutes

Step 1: Install and init

npm install -g i1n
i1n init

It'll ask for an API key (you can grab one at i1n.ai, Google or GitHub login). After that it detects your framework and sets up the locale directory automatically.

Step 2: Write your source strings

locales/en_us/common.json:

{
  "hero": {
    "title": "Welcome to our app",
    "subtitle": "The best tool for {task}",
    "cta": "Get Started"
  },
  "nav": {
    "home": "Home",
    "about": "About",
    "pricing": "Pricing"
  }
}

Nothing new here — same JSON structure you're probably used to.

Step 3: Push and translate

i1n push --translate es,fr,de,ja

One command. It pushes your keys, translates to 4 languages, and generates i1n.d.ts with autocomplete for every key. Variables like {task} are left untouched in every language.

Step 4: Use it

import { t } from 'i1n';

export function Hero() {
  return (
    <section>
      <h1>{t('hero.title')}</h1>
      <p>{t('hero.subtitle', { task: 'building products' })}</p>
      <button>{t('hero.cta')}</button>
    </section>
  );
}

If you typo a key, TypeScript yells at you before it ever hits production. No more t('hera.titl') silently rendering nothing.

If you're already on i18next or next-intl, there's a Bridge Mode that wraps your existing setup with type safety. One line, no migration. Details in the docs.

Bonus: MCP Server

This part is honestly the most fun. If you use Cursor, Claude Code, or Windsurf:

claude mcp add i1n -- npx i1n mcp

Now you can just tell your AI agent "internationalize this component" and it actually does it. Reads the file, extracts the strings, pushes them, translates everything, rewrites the code with t() calls. What used to take me an hour is like 30 seconds now.

What does your i18n setup look like? I've been going back and forth between next-intl and i18next with the App Router and I'm curious what other people landed on.