Sign in Start free

Translation key drift guard

Using English strings as translation keys is convenient until someone edits the English. The key no longer matches, every locale falls through to the key, and the page renders in English with no error, no warning and no failing test. The regression is invisible until a native speaker notices.

CATEGORY
International SEO
FORMAT
translation-key-drift-guard.md
STEPS
6
PRICE
Free - no account
WHEN TO REACH FOR THIS

Use on any site whose translation keys are the English source text, where editing a headline silently reverts every other language.

The skill file

translation-key-drift-guard.md 
---
name: translation-key-drift-guard
description: Use on any site whose translation keys are the English source text, where editing a headline silently reverts every other language.
---

# Translation key drift guard

Using English strings as translation keys is convenient until someone edits the English. The key no longer matches, every locale falls through to the key, and the page renders in English with no error, no warning and no failing test. The regression is invisible until a native speaker notices.

## What you need first

- The source tree containing the translation calls
- The locale files

## Method

1. Extract every literal passed to the translation function across templates and application code, handling both quote styles.
2. Compare that set against the keys present in each locale file. Anything in the source but missing from a locale is a string that will silently render in English.
3. Check placeholder parity in both directions: a key containing a named placeholder whose translation has dropped it produces a broken sentence at runtime, not an error.
4. Report keys present in a locale but absent from the source as orphans - safe to prune, and a signal that an English string was edited.
5. Wire the check into the release path so it exits non-zero. A check that nobody runs is not a check.
6. Prove it fails: delete one key and confirm the run breaks, then restore. An assertion never seen to fail is not trusted.

## What this produces

A per-locale report of missing keys, placeholder mismatches and orphans, with a non-zero exit that can gate a deploy.

## Where this goes wrong

- Building the check but never verifying it actually fails on a real regression
- Ignoring placeholder parity, which breaks sentences rather than merely reverting them
- Treating orphaned keys as noise when they are usually evidence that English copy was edited without updating the locales

---

From the QuQi skill library - https://www.quqi.io/skills/translation-key-drift-guard
Free to download · no account, no email

What you need first

  • The source tree containing the translation calls
  • The locale files

Method

  1. 01 Extract every literal passed to the translation function across templates and application code, handling both quote styles.
  2. 02 Compare that set against the keys present in each locale file. Anything in the source but missing from a locale is a string that will silently render in English.
  3. 03 Check placeholder parity in both directions: a key containing a named placeholder whose translation has dropped it produces a broken sentence at runtime, not an error.
  4. 04 Report keys present in a locale but absent from the source as orphans - safe to prune, and a signal that an English string was edited.
  5. 05 Wire the check into the release path so it exits non-zero. A check that nobody runs is not a check.
  6. 06 Prove it fails: delete one key and confirm the run breaks, then restore. An assertion never seen to fail is not trusted.

What this produces

A per-locale report of missing keys, placeholder mismatches and orphans, with a non-zero exit that can gate a deploy.

Where this goes wrong

  • Building the check but never verifying it actually fails on a real regression
  • Ignoring placeholder parity, which breaks sentences rather than merely reverting them
  • Treating orphaned keys as noise when they are usually evidence that English copy was edited without updating the locales

Use this skill in your own AI

The download is a plain markdown file with the name and trigger in its frontmatter. Where an assistant supports skills it can load itself, that frontmatter is what it reads to decide this one applies.

Claude Code Save it as ~/.claude/skills/translation-key-drift-guard/SKILL.md and Claude loads it on its own when what you are doing matches the trigger line. Put it in .claude/skills inside a project instead if the whole team should have it.
Claude Upload the file in the skills section of your settings. Once it is there it applies itself in any conversation where the trigger fits, so you do not have to remember it exists.
ChatGPT There is no skills format to install into, so paste the file contents into a Project instruction or a Custom GPT instead. It then applies to every chat in that project rather than only the one you paste it into.
Anything else Paste the markdown into the chat before your question. It works in any assistant, it just has to be pasted again each time.

Questions about this skill

When do I need this rather than relying on the test suite?

Use it on any site whose translation keys are the English source string. Tests do not catch the failure: an edited headline leaves the key unmatched, every locale falls through to it, and the page renders valid English with no error and no exception. Nothing goes red, so a native speaker noticing months later is the only other detection route.

What do I need in hand before starting?

The source tree containing the translation calls, and the locale files. Extract literals from templates and application code, handling both quote styles, since a scanner reading only one reports a clean run while half the calls were never seen. Strings assembled from config at runtime evade literal extraction completely and have to be listed by hand.

What do I end up with, and which part of it gets used?

A per-locale report of missing keys, placeholder mismatches and orphans, exiting non-zero. The exit code is the part that gets used: a report someone reads occasionally decays, one wired into the release path blocks the regression. Read the placeholder mismatches by hand, since a translation that dropped a named placeholder produces a broken sentence rather than English text.

What ruins this most often?

Building the check and never proving it fails. Delete one key, watch the run break, then restore it, because an assertion nobody has seen fail is not trusted and is quietly broken by any path change. The other costly habit is dismissing orphans as noise, when they are usually the evidence that English copy was edited without touching the locales.

More in International SEO

Hreflang reciprocity repair

Use when translated pages exist and are indexed but never surface for the right country, or when...

Locale redirect trap audit

Use when visitors report being unable to switch back to a language, or when a shared link opens...

RTL layout audit

Use before shipping Arabic, Hebrew, Farsi or Urdu, or when an RTL locale shows overlapping text,...

Multilingual sitemap coverage

Use when translated pages exist and are linked but receive no impressions, and the sitemap lists...