---
title: "Mark translations stale when the source · Agent Wranglers"
url: https://agentwranglers.se/playbook/localization/messages-and-translation/stale-translations
id: LOC-20
level: Recommended
updated: 2026-10-22
tokens: 1028
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Mark translations stale when the source changes

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Messages and translation](https://agentwranglers.se/playbook/localization/messages-and-translation.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: LOC-20
- Level: Recommended
- Chapter: [Messages and translation](https://agentwranglers.se/playbook/localization/messages-and-translation.md)
- Rule: When a source sentence changes, mark its translations as needing review in every language. A stale translation is never published as current.
- 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.
- How: 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](https://agentwranglers.se/playbook/localization/messages-and-translation/translation-completeness.md). For a meaning change, a new key is often safer than an edited one.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
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

```python
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)]
```

## Sources

- [GNU gettext manual (Fuzzy entries)](https://www.gnu.org/software/gettext/manual/html_node/Fuzzy-Entries.html)
- [GNU gettext manual (Invoking msgfmt, --use-fuzzy)](https://www.gnu.org/software/gettext/manual/html_node/msgfmt-Invocation.html)

## Related rules

- LOC-19 [Fail the build on missing or broken translations](https://agentwranglers.se/playbook/localization/messages-and-translation/translation-completeness.md) in Localization
- LOC-35 [Store translated content per record and language](https://agentwranglers.se/playbook/localization/apis-and-data/translated-content-storage.md) in Localization
- DOC-37 [Show readers when a translation is older than the source](https://agentwranglers.se/playbook/documentation/keeping-docs-current/stale-translation-banner.md) in Documentation
- SUP-24 [Update help content in the same release as the product](https://agentwranglers.se/playbook/customer-support/macros-and-help-articles/help-content-with-releases.md) in Customer support

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Fail the build on missing or broken translations](https://agentwranglers.se/playbook/localization/messages-and-translation/translation-completeness.md)
- Next: [Give translators context and a review step](https://agentwranglers.se/playbook/localization/messages-and-translation/translator-context.md)
- [Messages and translation](https://agentwranglers.se/playbook/localization/messages-and-translation.md)