Safely renaming a translation key ¶

You rename checkout.cta to checkout.submit, push, and the next morning the German, French and Japanese translations for that string are gone. The catalogue is not corrupt and nothing errored — the synchronisation job did exactly what it was told. It saw one key disappear and an unrelated key appear, archived the translations of the first, and queued the second as new work.

A rename is one of the few catalogue operations with no undo, because the loss happens in a system you do not control. This page covers why, and the procedure that avoids it.

Root cause: identity is the key, and only the key ¶

A translation memory system stores translations against an identifier. When the identifier changes, there is nothing left connecting the old translations to the new string — the source text may be byte-identical, but nothing in the format says “these are the same string under a new name.”

Some systems mitigate this with fuzzy matching: if the new key’s source text matches an archived unit exactly, the translation may be offered as a suggestion. That is a mitigation, not a guarantee. It depends on the archive being searched, on the match threshold, and on nobody having edited the source text in the same commit. Relying on it means relying on a heuristic to protect work that a translator was paid for.

The failure is worse when the rename and the locale files diverge across commits. If the English catalogue is renamed in one commit and the other locales in the next, there is a window in which the source has checkout.submit and every target still has checkout.cta. A sync running inside that window sees a key with no translations in any locale — which is exactly the state that triggers archival.

Minimal reproducible example ¶

# The rename that loses translations: source only, then push.
sed -i 's/"checkout.cta"/"checkout.submit"/' locales/en.json
git commit -am 'rename checkout cta key' && git push

# The nightly sync now reports:
#   + checkout.submit   (new, 0/4 locales)
#   - checkout.cta      (removed, translations archived)

Nothing in that output is wrong. The pipeline has no way to know the two lines describe one string.

The fix: move every locale in one commit, and leave an alias ¶

The mechanical rename is a single script that touches every catalogue at once, so no intermediate state exists for a sync to misread.

#!/usr/bin/env bash
# rename-key.sh OLD NEW — renames a key across every locale in one commit.
set -euo pipefail
OLD="$1"; NEW="$2"

for f in locales/*/*.json; do
  # jq preserves ordering and fails loudly on malformed JSON
  jq --arg o "$OLD" --arg n "$NEW" '
    if has($o) then . + {($n): .[$o]} | del(.[$o]) else . end
  ' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
done

# Call sites move in the same commit, so no build is ever broken mid-rename.
grep -rl "$OLD" src | xargs sed -i "s/${OLD}/${NEW}/g"

git add locales src
git commit -m "rename ${OLD} -> ${NEW} across all locales"

The alias is the second half, and it is what protects you from the things you did not think of — a cached client bundle, a revert, a feature branch merged a week later that still references the old key.

// One release cycle of protection, then delete this entry.
const ALIASES: Record<string, string> = {
  'checkout.cta': 'checkout.submit',
};

export function resolveKey(key: string): string {
  const target = ALIASES[key];
  if (target && process.env.NODE_ENV !== 'production') {
    console.warn(`[i18n] "${key}" is renamed to "${target}"; update the call site`);
  }
  return target ?? key;
}

Verification ¶

Two checks prove the rename landed cleanly: every locale has the new key, and no locale still has the old one.

# Every locale must carry the new key
for f in locales/*/*.json; do
  jq -e 'has("checkout.submit")' "$f" > /dev/null \
    || { echo "missing in $f"; exit 1; }
done

# No locale may still carry the old key
! grep -rq '"checkout.cta"' locales/ || { echo 'old key still present'; exit 1; }

# Expected
#   all 4 locales carry checkout.submit
#   old key fully removed

Add the first check to CI permanently, not just for this rename. Asserting that every locale file has the same key set catches the class of problem rather than the instance, and it is the same parity gate described in GitHub Actions i18n CI gates.

Renaming a whole namespace ¶

Moving one key is a small operation; moving a namespace is the same operation applied several hundred times, and the failure mode scales with it. Two properties make it survivable.

The first is that leaf keys must not change. If checkout.submit becomes payments.submit, only the namespace segment moved and every tool that matches on the trailing path has a chance of reconciling it. If the leaf changes at the same time, nothing can.

The second is that the files move as files. A namespace is usually one file per locale, so the operation is a git mv of each file plus a single rewrite of the namespace prefix inside them. Doing it that way keeps version history attached to the content, which matters six months later when someone asks why a string is worded the way it is.

#!/usr/bin/env bash
# move-namespace.sh OLD NEW — one commit, every locale, history preserved.
set -euo pipefail
OLD="$1"; NEW="$2"

for dir in locales/*/; do
  [ -f "$dir$OLD.json" ] || continue
  git mv "$dir$OLD.json" "$dir$NEW.json"
done

# Call sites name the namespace explicitly; update them in the same commit.
grep -rl "useTranslation('$OLD')" src | xargs sed -i "s/useTranslation('$OLD')/useTranslation('$NEW')/g"
git commit -m "move namespace $OLD -> $NEW"

The namespace alias is a single entry rather than one per key, which makes it cheap to keep for a full release cycle:

const NS_ALIASES: Record<string, string> = { checkout: 'payments' };
export const resolveNamespace = (ns: string) => NS_ALIASES[ns] ?? ns;

One caveat specific to namespaces: they are usually also the loading unit, so renaming one changes which chunk a page requests. A client holding a cached bundle will ask for the old chunk name after the deploy, which is a 404 rather than a missing translation. Keeping the old chunk served as a redirect, or simply deploying the alias before the rename, covers the window.

When to escalate ¶

If translations are already lost, the recovery path is the translation memory rather than the catalogue. Most systems keep archived units searchable for a period, and a pre-translation pass against the memory will restore exact matches automatically — the leverage mechanism described in translation memory and glossary management. Do this before translators start retranslating, because once a new unit is approved the old one stops being offered.

If your workflow renames keys frequently enough that this procedure is a burden, the keys are describing the wrong thing. Keys named after their content need renaming every time the copy changes; keys named after their role almost never need renaming at all. That is a catalog governance problem, and fixing it removes the operation rather than making it safer.

FAQ ¶

Related ¶

• String Catalog Governance — the naming rules that make renames rare in the first place.
• Translation Memory & Glossary Management — where lost translations can sometimes be recovered from.
• Angular localize missing translation IDs — the same loss, caused by a content hash rather than a deliberate rename.
• GitHub Actions i18n CI Gates — the key-parity gate that catches a half-finished rename.

Part of String Catalog Governance.