Test case example of issue and missing feature in `gulp-wp-pot`/`wp-pot`

README.md

Test case using gulp-wp-pot/wp-pot

This minimal test case shows two things concerning the gulp-wp-pot/wp-pot package.

1. An issue with duplicate translator hint descriptions ('extractor comments' in gettext)

If you use a translation string that has a placeholder (e.g. %s or %1$s) in multiple files, the plugin extracts these correctly. But it outputs the comment for each time is was used, so there are duplicates filling up the resulting .pot file. See result.pot, lines 17-18.

2. A missing nice-to-have-feature

If a translation string is used in multiple files, the filepath references are all concatenated on one line in the resulting .pot file. It would be nice if there was an option the have them split to separate lines for readability. In this test case I mimicked the feature using the gulp-replace package and a 'regex -> split -> join' string replacement. To see it in action, just uncomment lines 11 and 24 through 29 inside gulpfile.js.

first-file.php

<?php

/* translators: 1: the placeholder */
echo __( 'Some translation string with a placeholder (%s) description for translators.', 'test-case' );

gulpfile.js

const {
	src,
	dest
} = require('gulp');
const wpPot = require('gulp-wp-pot');
// const replace = require('gulp-replace');

function taskMakePOT() {
	return src( './**/*.php' )
		.pipe( wpPot( {
			domain: 'test-case',
			package: 'test-case',
			relativeTo: './',
		} ) )
		/**
		 * Nice feature to add:
		 * Split multiple file refs into separate lines in POT file
		 */
		// .pipe( replace(
		// 	/^#: .+?\.php:\d+(?:, .+?\.php:\d+)+$/gm,
		// 	function handleReplace( match, p1, offset, string ) {
		// 		return match.split(', ').join('\n#: ');
		// 	}
		// ) )
		.pipe( dest( 'result.pot' ) )
	;
}

exports.default = taskMakePOT;

package.json

{
  "name": "test-case",
  "version": "1.0.0",
  "description": "",
  "author": "",
  "license": "ISC",
  "dependencies": {
    "gulp": "^4.0.2",
    "gulp-replace": "^1.1.3",
    "gulp-wp-pot": "^2.5.0"
  }
}

result.pot

# Copyright (C) 2022 test-case
# This file is distributed under the same license as the test-case package.
msgid ""
msgstr ""
"Project-Id-Version: test-case\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2022-05-23 20:00+0000\n"
"X-Poedit-Basepath: ..\n"
"X-Poedit-KeywordsList: __;_e;_ex:1,2c;_n:1,2;_n_noop:1,2;_nx:1,2,4c;_nx_noop:1,2,3c;_x:1,2c;esc_attr__;esc_attr_e;esc_attr_x:1,2c;esc_html__;esc_html_e;esc_html_x:1,2c\n"
"X-Poedit-SearchPath-0: .\n"
"X-Poedit-SearchPathExcluded-0: *.js\n"
"X-Poedit-SourceCharset: UTF-8\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

#. translators: 1: the placeholder
#. translators: 1: the placeholder
#: first-file.php:4, second-file.php:6
msgid "Some translation string with a placeholder (%s) description for translators."
msgstr ""

second-file.php

<?php

$something_before = 'whatever';

/* translators: 1: the placeholder */
echo __( 'Some translation string with a placeholder (%s) description for translators.', 'test-case' );