@wordpress/eslint-plugin 22.11.0 → 22.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/eslint-plugin",
-	"version": "22.11.0",
+	"version": "22.13.0",
 	"description": "ESLint plugin for WordPress development.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -34,8 +34,8 @@
 		"@babel/eslint-parser": "7.25.7",
 		"@typescript-eslint/eslint-plugin": "^6.4.1",
 		"@typescript-eslint/parser": "^6.4.1",
-		"@wordpress/babel-preset-default": "^8.25.0",
-		"@wordpress/prettier-config": "^4.25.0",
+		"@wordpress/babel-preset-default": "^8.27.0",
+		"@wordpress/prettier-config": "^4.27.0",
 		"cosmiconfig": "^7.0.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.2",
@@ -66,5 +66,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d1acd76ffff33ab01f0a948d2f51e5e45c95158d"
+	"gitHead": "abe06a6f2aef8d03c30ea9d5b3e133f041e523b1"
 }

package/rules/__tests__/i18n-translator-comments.js

@@ -18,84 +18,155 @@ ruleTester.run( 'i18n-translator-comments', rule, {
 	valid: [
 		{
 			code: `
-// translators: %s: Color
-sprintf( __( 'Color: %s' ), color );`,
+		// translators: %s: Color
+		sprintf( __( 'Color: %s' ), color );`,
 		},
 		{
 			code: `
-sprintf(
-	// translators: %s: Address.
-	__( 'Address: %s' ),
-	address
-);`,
+		sprintf(
+			// translators: %s: Address.
+			__( 'Address: %s' ),
+			address
+		);`,
 		},
 		{
 			code: `
-// translators: %s: Color
-i18n.sprintf( i18n.__( 'Color: %s' ), color );`,
+		// translators: %s: Color
+		i18n.sprintf( i18n.__( 'Color: %s' ), color );`,
 		},
 		{
 			code: `
-sprintf(
-	/*
-	 * translators: %s is the name of the city we couldn't locate.
-	 * Replace the examples with cities related to your locale. Test that
-	 * they match the expected location and have upcoming events before
-	 * including them. If no cities related to your locale have events,
-	 * then use cities related to your locale that would be recognizable
-	 * to most users. Use only the city name itself, without any region
-	 * or country. Use the endonym (native locale name) instead of the
-	 * English name if possible.
-	 */
-	__( 'We couldn’t locate %s. Please try another nearby city. For example: Kansas City; Springfield; Portland.' ),
-templateParams.unknownCity
-);`,
+		sprintf(
+			/*
+			 * translators: %s is the name of the city we couldn't locate.
+			 * Replace the examples with cities related to your locale. Test that
+			 * they match the expected location and have upcoming events before
+			 * including them. If no cities related to your locale have events,
+			 * then use cities related to your locale that would be recognizable
+			 * to most users. Use only the city name itself, without any region
+			 * or country. Use the endonym (native locale name) instead of the
+			 * English name if possible.
+			 */
+			__( 'We couldn’t locate %s. Please try another nearby city. For example: Kansas City; Springfield; Portland.' ),
+		templateParams.unknownCity
+		);`,
+		},
+		{
+			code: `
+		// translators: %s: Name
+		sprintf( __( 'Name: %s' ), 'hi' );`,
+		},
+		{
+			code: `// translators: city: City
+sprintf( __( 'City: %(city)s' ),{ city: 'New York' });`,
+		},
+		{
+			code: `
+// translators: 1: Address, 2: City
+sprintf( __( 'Address: %1$s, City: %2$s' ), address, city );`,
+		},
+		{
+			code: `
+// translators: %s: 1 or 2
+sprintf( __( '%s point' ), number );`,
+		},
+		{
+			code: `
+/* translators: accessibility text. %1: current block position (number). %2: next block position (number) */
+	__( 'Move block left from position %1$s to position %2$s');`,
+		},
+		{
+			code: `
+// translators: %1s: Title of a media work from Openverse; %2s: Work's licence e.g: "CC0 1.0".
+_x( '"%1$s"/ %2$s', 'caption' );
+`,
+		},
+		{
+			code: `
+// translators: %1$s: Title of a media work from Openverse; %2$s: Work's licence e.g: "CC0 1.0".
+_x( '"%1$s"/ %2$s', 'caption' );
+			`,
 		},
 	],
 	invalid: [
 		{
 			code: `
-sprintf( __( 'Color: %s' ), color );`,
+		sprintf( __( 'Color: %s' ), color );`,
 			errors: [ { messageId: 'missing' } ],
 		},
 		{
 			code: `
-sprintf(
-	__( 'Address: %s' ),
-	address
-);`,
+		sprintf(
+			__( 'Address: %s' ),
+			address
+		);`,
 			errors: [ { messageId: 'missing' } ],
 		},
 		{
 			code: `
-// translators: %s: Name
-var name = '';
-sprintf( __( 'Name: %s' ), name );`,
+		// translators: %s: Name
+		var name = '';
+		sprintf( __( 'Name: %s' ), name );`,
 			errors: [ { messageId: 'missing' } ],
 		},
 		{
 			code: `
-// translators: %s: Surname
-console.log(
-	sprintf( __( 'Surname: %s' ), name )
-);`,
+		// translators: %s: Surname
+		console.log(
+			sprintf( __( 'Surname: %s' ), name )
+		);`,
 			errors: [ { messageId: 'missing' } ],
 		},
 		{
 			code: `
-// translators: %s: Preference
-console.log(
-	sprintf(
-		__( 'Preference: %s' ),
-		preference
-	)
-);`,
+		// translators: %s: Preference
+		console.log(
+			sprintf(
+				__( 'Preference: %s' ),
+				preference
+			)
+		);`,
 			errors: [ { messageId: 'missing' } ],
 		},
 		{
 			code: `
-i18n.sprintf( i18n.__( 'Color: %s' ), color );`,
+		i18n.sprintf( i18n.__( 'Color: %s' ), color );`,
 			errors: [ { messageId: 'missing' } ],
 		},
+		{
+			code: `// translators: %d: Address
+		i18n.sprintf( i18n.__( 'Address: %s' ), address );`,
+			errors: [ { messageId: 'missingKeys' } ],
+		},
+		{
+			code: ` // translators: %s: City
+		i18n.sprintf( i18n.__( 'City: %(city)s' ), { city: 'New York' } );`,
+			errors: [
+				{ messageId: 'missingKeys', data: { keys: [ 'city' ] } },
+			],
+		},
+		{
+			code: `// translators: 1: Address
+		i18n.sprintf( i18n.__( 'Address: %1$s, City: %2$s' ), address, city );`,
+			errors: [ { messageId: 'missingKeys', data: { keys: [ '2' ] } } ],
+		},
+		{
+			code: `// translators: %s: City %d: Number
+		i18n.sprintf( i18n.__( 'City: %s' ), city, number );`,
+			errors: [
+				{ messageId: 'extraPlaceholders', data: { keys: [ '%d' ] } },
+			],
+		},
+		{
+			code: `
+// translators: %s: hi, 1: okay, 2: bye
+		i18n.sprintf( i18n.__( '%s point' ), number );`,
+			errors: [
+				{
+					messageId: 'extraPlaceholders',
+					data: { keys: [ '1', '2' ] },
+				},
+			],
+		},
 	],
 } );

package/rules/i18n-translator-comments.js

@@ -8,6 +8,53 @@ const {
 	getTranslateFunctionArgs,
 	getTextContentFromNode,
 } = require( '../utils' );
+const { REGEXP_COMMENT_PLACEHOLDER } = require( '../utils/constants' );
+
+/**
+ * Extracts placeholders from a string.
+ *
+ * @param {string} str - The string to extract placeholders from.
+ * @return {string[]} An array of objects representing the placeholders found in the string.
+ */
+function extractPlaceholders( str ) {
+	const matches = [];
+	let match;
+	REGEXP_SPRINTF_PLACEHOLDER.lastIndex = 0;
+
+	while ( ( match = REGEXP_SPRINTF_PLACEHOLDER.exec( str ) ) !== null ) {
+		const index = match[ 3 ]; // from %1$s
+		const name = match[ 5 ]; // from %(name)s
+		matches.push( index ?? name ?? match[ 0 ] );
+	}
+	return matches;
+}
+
+/**
+ * Extracts translator keys from a comment text.
+ *
+ * @param {string} commentText - The text of the comment to extract keys from.
+ * @return	 {Map<string, boolean>} A set of translator keys found in the comment text.
+ */
+function extractTranslatorKeys( commentText ) {
+	const keys = new Map();
+	let match;
+
+	match = commentText.match( /translators:\s*(.*)/i );
+	if ( ! match ) {
+		return keys;
+	}
+
+	const commentBody = match[ 1 ];
+
+	// Match placeholders in the comment body.
+	while (
+		( match = REGEXP_COMMENT_PLACEHOLDER.exec( commentBody ) ) !== null
+	) {
+		keys.set( match[ 1 ], keys.get( match[ 1 ] ) || match[ 2 ] === ':' );
+	}
+
+	return keys;
+}
 
 module.exports = {
 	meta: {
@@ -15,6 +62,10 @@ module.exports = {
 		messages: {
 			missing:
 				'Translation function with placeholders is missing preceding translator comment',
+			missingKeys:
+				'Translator comment missing description(s) for placeholder(s): {{ keys }}.',
+			extraPlaceholders:
+				'Translator comment has extra placeholder(s): {{ keys }}.',
 		},
 	},
 	create( context ) {
@@ -98,6 +149,82 @@ module.exports = {
 					}
 
 					if ( /translators:\s*\S+/i.test( commentText ) ) {
+						const keysInComment =
+							extractTranslatorKeys( commentText );
+						const placeholdersUsed =
+							candidates.flatMap( extractPlaceholders );
+
+						const keysInCommentArr = [ ...keysInComment.keys() ];
+
+						// Check and filter placeholders that are not present in the comment.
+						const missing = placeholdersUsed.filter( ( key ) => {
+							// Regex to match the key and its potential formats in the array.
+							const regex = new RegExp( `%?${ key }(\\$[sdf])?` );
+							return ! keysInCommentArr.some( ( y ) =>
+								regex.test( y )
+							);
+						} );
+
+						if ( missing.length > 0 ) {
+							context.report( {
+								node,
+								messageId: 'missingKeys',
+								data: {
+									keys: missing.join( ', ' ),
+								},
+							} );
+
+							return;
+						}
+
+						const extra = keysInComment.size
+							? [ ...keysInComment.keys() ].filter( ( key ) => {
+									const normalizedKey = key.replace(
+										/^%/,
+										''
+									);
+
+									// Only allow numeric or printf-style placeholders
+									const isNumbered = /^[0-9]+$/.test(
+										normalizedKey
+									);
+									const isPrintf = [
+										'%s',
+										'%d',
+										'%f',
+									].includes( key );
+
+									// Only add if it's not already in allowedUsed
+									const isValidType =
+										( isNumbered &&
+											keysInComment.get(
+												normalizedKey
+											) ) ||
+										isPrintf;
+									const isUnused =
+										! placeholdersUsed.includes( key ) &&
+										! placeholdersUsed.includes(
+											normalizedKey
+										);
+
+									return isValidType && isUnused;
+							  } )
+							: [];
+
+						// console.log({extra, keysInComment, placeholdersUsed});
+
+						if ( extra.length > 0 ) {
+							context.report( {
+								node,
+								messageId: 'extraPlaceholders',
+								data: {
+									keys: extra.join( ',' ),
+								},
+							} );
+
+							return;
+						}
+
 						return;
 					}
 				}

package/utils/constants.js

@@ -55,8 +55,24 @@ const REGEXP_SPRINTF_PLACEHOLDER =
 const REGEXP_SPRINTF_PLACEHOLDER_UNORDERED =
 	/(?:(?<!%)%[+-]?(?:(?:0|'.)?-?[0-9]*(?:\.(?:[ 0]|'.)?[0-9]+)?|(?:[ ])?-?[0-9]+(?:\.(?:[ 0]|'.)?[0-9]+)?)[bcdeEfFgGosuxX])/;
 
+/**
+ * Regular expression matching comment placeholders.
+ *
+ * /(?:^|\s|,)\s*(%[sdf]|%?[a-zA-Z0-9_]+|%[0-9]+\$?[sdf]{0,1})(:)?/g;
+ * 		▲			▲			▲				▲		  ▲
+ * 		│			 │			  │ 				│		  │
+ * 		│			 │			  │					│		  └─ Match colon at the end of the placeholder ( optional )
+ * 		│			 │			  │					└─ Match a Index placeholder but allow variations (e.g. %1, %1s, %1$d)
+ * 		│			 │			  └─ Match a placeholder with index or named argument (e.g. %1, %name, %2)
+ * 		│			 └─ Match Unamed placeholder (e.g. %s, %d)
+ * 		└─ Match the start of string, whitespace, or comma
+ */
+const REGEXP_COMMENT_PLACEHOLDER =
+	/(?:^|\s|,)\s*(%[sdf]|%?[a-zA-Z0-9_]+|%[0-9]+\$?[sdf]{0,1})(:)?/g;
+
 module.exports = {
 	TRANSLATION_FUNCTIONS,
 	REGEXP_SPRINTF_PLACEHOLDER,
 	REGEXP_SPRINTF_PLACEHOLDER_UNORDERED,
+	REGEXP_COMMENT_PLACEHOLDER,
 };