Add dedicated wp i18n audit command with JSON and GitHub Actions output formats

composer.json

@@ -41,6 +41,7 @@
         "bundled": true,
         "commands": [
             "i18n",
+            "i18n audit",
             "i18n make-pot",
             "i18n make-json",
             "i18n make-mo",

features/audit.feature

@@ -0,0 +1,258 @@
+Feature: Audit strings in a WordPress project
+
+  Background:
+    Given a WP install
+
+  Scenario: Audits a plugin for translation issues
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: The string "Hello %s" contains placeholders but has no "translators:" comment to clarify their meaning.
+      """
+    And STDERR should contain:
+      """
+      Warning: Found 1 issue.
+      """
+    And the return code should be 0
+
+  Scenario: Audits a plugin and finds no issues
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello World', 'foo-plugin' );
+      """
+
+    When I run `wp i18n audit foo-plugin`
+    Then STDOUT should contain:
+      """
+      Success: No issues found.
+      """
+    And STDERR should be empty
+
+  Scenario: Outputs audit results as JSON
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'foo-plugin' );
+      """
+
+    When I run `wp i18n audit foo-plugin --format=json`
+    Then STDOUT should contain:
+      """
+      "file": "foo-plugin.php"
+      """
+    And STDOUT should contain:
+      """
+      "line": 7
+      """
+    And STDOUT should contain:
+      """
+      "message": "The string \"Hello %s\" contains placeholders but has no \"translators:\" comment to clarify their meaning."
+      """
+    And STDOUT should contain:
+      """
+      "code": "missing-translator-comment"
+      """
+
+  Scenario: Outputs audit results in GitHub Actions format
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'foo-plugin' );
+      """
+
+    When I run `wp i18n audit foo-plugin --format=github-actions`
+    Then STDOUT should contain:
+      """
+      ::warning file=foo-plugin.php,line=7::The string "Hello %s" contains placeholders but has no "translators:" comment to clarify their meaning.
+      """
+
+  Scenario: Detects multiple unordered placeholders
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s %s', 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: Multiple placeholders should be ordered.
+      """
+
+  Scenario: Detects strings without translatable content
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( '%s', 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: Found string without translatable content.
+      """
+
+  Scenario: Detects multiple translator comments
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      /* translators: Comment 1 */
+      __( 'Hello World', 'foo-plugin' );
+
+      /* translators: Comment 2 */
+      __( 'Hello World', 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:
+      """
+    And STDERR should contain:
+      """
+      different translator comments
+      """
+
+  Scenario: Detects missing singular placeholder
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      _n( 'One comment', '%s Comments', $count, 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: Missing singular placeholder, needed for some languages.
+      """
+
+  Scenario: Detects mismatched placeholders in plural strings
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      _n( '%s Comment', '%d Comments', $count, 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: Mismatched placeholders for singular and plural string.
+      """
+
+  Scenario: Respects --ignore-domain flag
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'different-domain' );
+      """
+
+    When I try `wp i18n audit foo-plugin --ignore-domain`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: The string "Hello %s" contains placeholders but has no "translators:" comment to clarify their meaning.
+      """
+
+  Scenario: Respects --skip-php flag
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'foo-plugin' );
+      """
+
+    When I run `wp i18n audit foo-plugin --skip-php`
+    Then STDOUT should contain:
+      """
+      Success: No issues found.
+      """
+
+  Scenario: Shows file before warning message in plaintext format
+    Given an empty foo-plugin directory
+    And a foo-plugin/foo-plugin.php file:
+      """
+      <?php
+      /**
+       * Plugin Name: Foo Plugin
+       * Text Domain: foo-plugin
+       */
+
+      __( 'Hello %s', 'foo-plugin' );
+      """
+
+    When I try `wp i18n audit foo-plugin --format=plaintext`
+    Then STDERR should contain:
+      """
+      Warning: foo-plugin.php:7: The string "Hello %s" contains placeholders but has no "translators:" comment to clarify their meaning.
+      """

i18n-command.php

@@ -33,3 +33,15 @@
 WP_CLI::add_command( 'i18n make-php', '\WP_CLI\I18n\MakePhpCommand' );
 
 WP_CLI::add_command( 'i18n update-po', '\WP_CLI\I18n\UpdatePoCommand' );
+
+WP_CLI::add_command(
+	'i18n audit',
+	'\WP_CLI\I18n\AuditCommand',
+	array(
+		'before_invoke' => static function () {
+			if ( ! function_exists( 'mb_ereg' ) ) {
+				WP_CLI::error( 'The mbstring extension is required for string extraction to work reliably.' );
+			}
+		},
+	)
+);