Keep translation catalogs stable across code-only changes

AGENTS.md

@@ -104,7 +104,9 @@ formatting needs correction. Do not replace the repository ruleset with a bare
 - Browser JS/block behavior: `npm run test:js`; affected UI flows: `make test-e2e`.
 - Translations: `make translations` (`composer make-translations`, vendored WP-CLI;
   never the wp-env container's `wp`), then `make check-untranslated`; commit the
-  generated catalogs.
+  generated catalogs. Catalog references name files without line numbers, so a
+  code change only touches `languages/` when a string is added, removed or moved
+  to another file.
 - Architecture records: `make architecture-check`.
 - Workflows: `actionlint`.
 - Plugin distribution: `make check-plugin`; inspect the actual release archive.

bin/pot-strip-line-numbers.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Reduce `#:` source references in the POT file to file names only.
+ *
+ * `wp i18n make-pot` writes `#: file:line` references, so any code change that
+ * shifts a translatable string's line rewrote every catalog. `wp i18n make-json`
+ * still needs the file names to map JavaScript strings to their scripts, so the
+ * references are kept, without line numbers and without repeated files.
+ *
+ * @package Exelearning
+ */
+
+$pot   = dirname( __DIR__ ) . '/languages/exelearning.pot';
+$lines = file( $pot );
+if ( false === $lines ) {
+	fwrite( STDERR, "pot-strip-line-numbers: cannot read {$pot}\n" );
+	exit( 1 );
+}
+
+foreach ( $lines as $i => $line ) {
+	if ( 0 === strncmp( $line, '#: ', 3 ) ) {
+		$files       = preg_replace( '/:\d+$/', '', preg_split( '/\s+/', trim( substr( $line, 3 ) ) ) );
+		$lines[ $i ] = '#: ' . implode( ' ', array_unique( $files ) ) . "\n";
+	}
+}
+
+if ( false === file_put_contents( $pot, implode( '', $lines ) ) ) {
+	fwrite( STDERR, "pot-strip-line-numbers: cannot write {$pot}\n" );
+	exit( 1 );
+}
+exit( 0 );

composer.json

@@ -16,6 +16,7 @@
         "phpcbf": "phpcbf --standard=.phpcs.xml.dist",
         "make-pot": "wp i18n make-pot . languages/exelearning.pot --slug=exelearning --domain=exelearning --exclude=vendor,node_modules,tests,wp,wp-content,dist,exelearning,bin",
         "pot-remove-ctime": "sed -i.bak '/POT-Creation-Date:/d' languages/exelearning.pot && rm languages/exelearning.pot.bak",
+        "pot-strip-line-numbers": "@php bin/pot-strip-line-numbers.php",
         "po": "@php bin/po-update.php",
         "make-mo": "wp i18n make-mo languages/ languages/",
         "make-php": "wp i18n make-php languages/ languages/",
@@ -24,6 +25,7 @@
         "make-translations": [
             "@make-pot",
             "@pot-remove-ctime",
+            "@pot-strip-line-numbers",
             "@po",
             "@untranslated",
             "@make-mo",
@@ -39,6 +41,7 @@
         "check-untranslated": [
             "@make-pot",
             "@pot-remove-ctime",
+            "@pot-strip-line-numbers",
             "@po",
             "@untranslated",
             "@make-mo",