The update-po command removes obsolete translations (#~ entries) and file-level comments (copyright notices) by default. Users maintaining translation history in VCS need a way to preserve this content.

Changes

• Added --purge flag: Conditionally excludes Merge::REMOVE and Merge::COMMENTS_THEIRS from merge operation. Defaults to true (purging enabled)
• Implemented file-level comment preservation: The gettext library doesn't preserve comments before the header entry, so added helpers to extract/restore them manually using atomic file operations
• Added test coverage: Two scenarios validating flag behavior and default behavior

Usage

# Default: removes obsolete entries and comments (purging enabled by default)
$ wp i18n update-po plugin.pot plugin-de_DE.po

# Explicitly enable purging (same as default)
$ wp i18n update-po plugin.pot plugin-de_DE.po --purge

# Preserve obsolete entries and comments
$ wp i18n update-po plugin.pot plugin-de_DE.po --no-purge

Input PO with obsolete content:

# Copyright (C) 2023 ACME
msgid ""
msgstr ""

#: file.php:10
msgid "Current"
msgstr "Aktuell"

#~ msgid "Obsolete"
#~ msgstr "Veraltet"

With --no-purge, all content is preserved while new strings from the POT are added. By default (or with --purge), copyright comments and obsolete entries are removed. WP-CLI automatically translates --no-purge to --purge=false behind the scenes.

[!WARNING]

• x] Yes, I reviewed the [contribution guidelines.

Describe your use case and the problem you are facing
update-po doesn't preserve unused translations/comments inside the PO files.
As Gettext editors like POEdit use their own translation database and VCS are usually used, this isn't a big deal and may de-clutter the PO file. - But an option for keeping this extra stuff may still be helpful in some cases.

Describe the solution you'd like
An option that lets update-po keep the unused translations/comments inside the PO files.

Example:
Input PO:

# Copyright (C) 2022 ACME
# This file is distributed under the proprietary.
msgid ""
msgstr ""
"Project-Id-Version: Test Theme 1.0.0\n"
[...]

#: theme.json
msgctxt "Color name"
msgid "Yellow"
msgstr "Gelb"

#~ msgctxt "Font size name"
#~ msgid "Small"
#~ msgstr "Klein"

Output PO (as you can see the extra Copyright comment and the unused translation were both stripped):

msgid ""
msgstr ""
"Project-Id-Version: Test Theme 1.0.0\n"
[...]

#: theme.json
msgctxt "Color name"
msgid "Yellow"
msgstr "Gelb"
````</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@swissspidy</author>
Thanks for sharing this suggestion 👍 

I'm not sure if <a href="https://github.com/php-gettext/Gettext/tree/4.x">the gettext library we use</a> supports that, but at first glance it looks like it at least does extract `#` and `#~` comments:

https://github.com/php-gettext/Gettext/blob/3e7460f8d9c90174824e3f39240bd578bb3d376a/src/Extractors/Po.php#L47-L59

Then the question is whether these can be kept during the update/merge.</comment_new>
</comments>

• Fixes update-po: Preserve unused translations/comments? #334

• Fixes update-po: Preserve unused translations/comments? #334

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.