i18n-command icon indicating copy to clipboard operation
i18n-command copied to clipboard
verified publisher icon wp-cli

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

Open Copilot opened this issue 3 months ago • 3 comments

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

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 wp-cli/i18n-command#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

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 wp-cli/i18n-command#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.

Copilot avatar Nov 03 '25 13:11 Copilot

Codecov Report

:x: 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 :warning:

:loudspeaker: Thoughts on this report? Let us know!

codecov[bot] avatar Nov 03 '25 14:11 codecov[bot]

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

swissspidy avatar Nov 03 '25 20:11 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.

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:

Copilot avatar Nov 03 '25 20:11 Copilot