Add --purge flag to control removal of obsolete translations and comments in update-po

[Copilot]

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]

Original prompt

---

This section details on the original issue you should resolve

<filter_complete></filter_complete>

<issue_title>update-po: Preserve unused translations/comments?</issue_title>
<issue_description>## Feature Request

• 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

Original prompt

---

This section details on the original issue you should resolve

<issue_title>update-po: Preserve unused translations/comments?</issue_title>
<issue_description>## Feature Request

• 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><body>
Thanks for sharing this suggestion 👍 

I'm not sure if [the gettext library we use](https://github.com/php-gettext/Gettext/tree/4.x) 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.</body></comment_new>
</comments>

• 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.

[codecov]

Codecov Report

❌ Patch coverage is 86.48649% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/UpdatePoCommand.php	86.48%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[swissspidy]

@copilot Invert & rename the flag to --purge and make purging the default. Then opt-out can be done with --no-purge, which WP-CLI automatically translates to --purge=false behind the scenes.

[Copilot]

@copilot Invert & rename the flag to --purge and make purging the default. Then opt-out can be done with --no-purge, which WP-CLI automatically translates to --purge=false behind the scenes.

Done! Changed the flag from --skip-purge to --purge with inverted logic. Purging is now the default (enabled), and users can opt-out with --no-purge which WP-CLI automatically translates to --purge=false.

Changes in commit 86fabf4:

• Renamed flag to --purge with default value true
• Inverted conditional logic
• Updated all documentation and examples
• Updated test scenarios

Tested all three scenarios:

• Default (purging enabled) ✓
• --purge (explicit) ✓
• --no-purge (opt-out) ✓

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/EFTEC/BladeOne/zipball/a19bf66917de0b29836983db87a455a4f6e32148
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/mck89/peast/zipball/c6a63f32410d2e4ee2cd20fe94b35af147fb852d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/php-gettext/Gettext/zipball/11af89ee6c087db3cf09ce2111a150bca5c46e12
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/php-gettext/Languages/zipball/0b0b0851c55168e1dfb14305735c64019732b5f1
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/symfony/finder/zipball/9f696d2f1e340484b4683f7853b273abff94421f
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/wp-cli/mustache.php/zipball/ca23b97ac35fbe01c160549eb634396183d04a59
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/wp-cli/php-cli-tools/zipball/f12b650d3738e471baed6dd47982d53c5c0ab1c3
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/wp-cli/spyc/zipball/6aa0b4da69ce9e9a2c8402dab8d43cf32c581cc7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)
• https://api.github.com/repos/wp-cli/wp-cli/zipball/03d30d4138d12b4bffd8b507b82e56e129e0523f
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/YRVJ9u /usr/bin/composer install --no-dev --no-interaction (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)