Agent Wranglers

LOC-20Recommended

Mark translations stale when the source changes

When a source sentence changes, mark its translations as needing review in every language. A stale translation is never published as current.

By Agent Wranglers. Updated .

How to do it

Keys often stay the same while the English text changes meaning, such as "Delete" becoming "Archive". The old translation then says the wrong thing. Store a hash of the source text with each translation. Gettext's msgmerge marks such entries as fuzzy, and translation platforms flag them too. Treat stale entries like missing ones in Fail the build on missing or broken translations. For a meaning change, a new key is often safer than an edited one.

Examples

JavaScript example

import { createHash } from 'node:crypto';
const sourceHash = text => createHash('sha256').update(text).digest('hex').slice(0, 12);
export const staleKeys = (source, translations) =>
  Object.keys(source).filter(key => translations[key] && translations[key].sourceHash !== sourceHash(source[key]));

Python example

import hashlib

def source_hash(text: str) -> str:
    return hashlib.sha256(text.encode()).hexdigest()[:12]

def stale_keys(source: dict[str, str], translations: dict[str, dict]) -> list[str]:
    return [key for key, text in source.items() if key in translations and translations[key]["source_hash"] != source_hash(text)]

How to check

A test changes one source sentence and runs the update step. That key is marked stale in every language, and the completeness check reports it.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/localization/messages-and-translation/stale-translations">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.