# What changed in translate-toolkit

> 23 changes in translate-toolkit 3 from its official release notes, upgrade guides and advisories: 1 breaking, 3 new APIs and options. Each one cited. Sources checked 2026-10-25. HTML: https://unstale.sh/pypi/translate-toolkit/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## translate-toolkit 3

### Breaking changes

- Building the documentation now requires Python 3.14 or newer. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)

### New APIs and options

- Adds a Catalan language module that disables inappropriate acronym and capitalization checks. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)
- Gettext PO supports an opt-in SPDX format for contributor comments while preserving historical years and unrelated copyright notices. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Exposes ordered term alternatives with IDs, administrative status, and scoped notes. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)

### Performance

- Restores embedded blocks in one pass to improve performance on large documents. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)
- Indexes contexts by name to speed up parsing files with many contexts. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)

### Behavior and default changes

- When no exact language match exists, lookup falls back from bare language codes to default-country variants. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)

### Tooling

- Improves type annotations for translation checks and JSON storage. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)

### Fixes and other changes

- Preserves newlines when converting Chinese punctuation. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)
- Exports every non-empty plural translation, pairing the first form with the singular source and subsequent forms with the plural source. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)
- Checks plural translations against their matching source forms to avoid false positives in placeholder and other source-dependent checks. (3.20.1) — [release notes](https://github.com/translate/translate/releases/tag/3.20.1)
- Editing existing units preserves translations, XML metadata, plural keys, and retained YAML and TOML documents. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Preserves translations identical to the source before trying legacy lookup keys and avoids consuming duplicate translation occurrences. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Keeps lookup indexes in sync when editing sources, keys, and contexts. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Editing matched terms preserves existing XML language tags. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Editing alternatives preserves term IDs, metadata, and unrelated XML. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Usable terms remain available when another term is deprecated or the selected target language is missing. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Fixes copying wrapper children during XML generation. (3.20.0) — [release notes](https://github.com/translate/translate/releases/tag/3.20.0)
- Keeps direct single-variable format references with their plural units. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)
- Reports missing stopword files correctly. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)
- Rejects malformed messages with invalid lengths. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)
- Corrects detection for script-specific and previously missing language codes. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)
- XML-based formats now honor inherited xml:space attributes to preserve significant whitespace. (3.19.19) — [release notes](https://github.com/translate/translate/releases/tag/3.19.19)