From 9ac09f5a673aa10531df714640fd6fd9ef220d11 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov.ru@gmail.com>
Date: Mon, 15 Nov 2021 16:45:01 +0000
Subject: [PATCH] Taxonomy: Clarify the taxonomy labels for customizing the
 field descriptions on Edit Tags screen:

* Update the label names to make it clear that these descriptions are not for the term name or slug itself, but for the Name, Slug, Parent, and Description fields:
 * `name_field_description`
 * `slug_field_description`
 * `parent_field_description`
 * `desc_field_description`
* Update the array structure to make it clear that the default values for these labels are the same for both hierarchical and non-hierarchical taxonomies, with the exception of `parent_field_description`.
* Add documentation and a `@since` note for the new labels.

Follow-up to [52094].

Fixes #43060.
Built from https://develop.svn.wordpress.org/trunk@52163


git-svn-id: http://core.svn.wordpress.org/trunk@51755 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/edit-tag-form.php |  8 ++++----
 wp-admin/edit-tags.php     |  8 ++++----
 wp-includes/taxonomy.php   | 28 ++++++++++++++++++++++++----
 wp-includes/version.php    |  2 +-
 4 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/wp-admin/edit-tag-form.php b/wp-admin/edit-tag-form.php
index 0c6e1994b9..d0d8f4af5e 100644
--- a/wp-admin/edit-tag-form.php
+++ b/wp-admin/edit-tag-form.php
@@ -146,7 +146,7 @@ if ( isset( $tag->name ) ) {
 		<tr class="form-field form-required term-name-wrap">
 			<th scope="row"><label for="name"><?php _ex( 'Name', 'term name' ); ?></label></th>
 			<td><input name="name" id="name" type="text" value="<?php echo $tag_name_value; ?>" size="40" aria-required="true" />
-			<p class="description"><?php echo $tax->labels->name_description; ?></p></td>
+			<p class="description"><?php echo $tax->labels->name_field_description; ?></p></td>
 		</tr>
 <?php if ( ! global_terms_enabled() ) { ?>
 		<tr class="form-field term-slug-wrap">
@@ -168,7 +168,7 @@ if ( isset( $tag->name ) ) {
 			$slug = isset( $tag->slug ) ? apply_filters( 'editable_slug', $tag->slug, $tag ) : '';
 			?>
 			<td><input name="slug" id="slug" type="text" value="<?php echo esc_attr( $slug ); ?>" size="40" />
-			<p class="description"><?php echo $tax->labels->slug_description; ?></p></td>
+			<p class="description"><?php echo $tax->labels->slug_field_description; ?></p></td>
 		</tr>
 <?php } ?>
 <?php if ( is_taxonomy_hierarchical( $taxonomy ) ) : ?>
@@ -195,7 +195,7 @@ if ( isset( $tag->name ) ) {
 				<?php if ( 'category' === $taxonomy ) : ?>
 					<p class="description"><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
 				<?php else : ?>
-					<p class="description"><?php echo $tax->labels->parent_description; ?></p>
+					<p class="description"><?php echo $tax->labels->parent_field_description; ?></p>
 				<?php endif; ?>
 			</td>
 		</tr>
@@ -203,7 +203,7 @@ if ( isset( $tag->name ) ) {
 		<tr class="form-field term-description-wrap">
 			<th scope="row"><label for="description"><?php _e( 'Description' ); ?></label></th>
 			<td><textarea name="description" id="description" rows="5" cols="50" class="large-text"><?php echo $tag->description; // textarea_escaped ?></textarea>
-			<p class="description"><?php echo $tax->labels->description_description; ?></p></td>
+			<p class="description"><?php echo $tax->labels->desc_field_description; ?></p></td>
 		</tr>
 		<?php
 		// Back compat hooks.
diff --git a/wp-admin/edit-tags.php b/wp-admin/edit-tags.php
index dc3440043d..8cd22fa184 100644
--- a/wp-admin/edit-tags.php
+++ b/wp-admin/edit-tags.php
@@ -454,13 +454,13 @@ if ( $can_edit_terms ) {
 <div class="form-field form-required term-name-wrap">
 	<label for="tag-name"><?php _ex( 'Name', 'term name' ); ?></label>
 	<input name="tag-name" id="tag-name" type="text" value="" size="40" aria-required="true" />
-	<p><?php echo $tax->labels->name_description; ?></p>
+	<p><?php echo $tax->labels->name_field_description; ?></p>
 </div>
 	<?php if ( ! global_terms_enabled() ) : ?>
 <div class="form-field term-slug-wrap">
 	<label for="tag-slug"><?php _e( 'Slug' ); ?></label>
 	<input name="slug" id="tag-slug" type="text" value="" size="40" />
-	<p><?php echo $tax->labels->slug_description; ?></p>
+	<p><?php echo $tax->labels->slug_field_description; ?></p>
 </div>
 <?php endif; // global_terms_enabled() ?>
 	<?php if ( is_taxonomy_hierarchical( $taxonomy ) ) : ?>
@@ -505,14 +505,14 @@ if ( $can_edit_terms ) {
 		<?php if ( 'category' === $taxonomy ) : ?>
 		<p><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
 	<?php else : ?>
-		<p><?php echo $tax->labels->parent_description; ?></p>
+		<p><?php echo $tax->labels->parent_field_description; ?></p>
 	<?php endif; ?>
 </div>
 	<?php endif; // is_taxonomy_hierarchical() ?>
 <div class="form-field term-description-wrap">
 	<label for="tag-description"><?php _e( 'Description' ); ?></label>
 	<textarea name="description" id="tag-description" rows="5" cols="40"></textarea>
-	<p><?php echo $tax->labels->description_description; ?></p>
+	<p><?php echo $tax->labels->desc_field_description; ?></p>
 </div>
 
 	<?php
diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index e0d848a9f7..643a1a6f05 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -589,6 +589,8 @@ function unregister_taxonomy( $taxonomy ) {
  * @since 4.9.0 Added the `most_used` and `back_to_items` labels.
  * @since 5.7.0 Added the `filter_by_item` label.
  * @since 5.8.0 Added the `item_link` and `item_link_description` labels.
+ * @since 5.9.0 Added the `name_field_description`, `slug_field_description`,
+ *              `parent_field_description`, and `desc_field_description` labels.
  *
  * @param WP_Taxonomy $tax Taxonomy object.
  * @return object {
@@ -605,6 +607,19 @@ function unregister_taxonomy( $taxonomy ) {
  *     @type string $parent_item                This label is only used for hierarchical taxonomies. Default
  *                                              'Parent Category'.
  *     @type string $parent_item_colon          The same as `parent_item`, but with colon `:` in the end.
+ *     @type string $name_field_description     Description for the Name field on Edit Tags screen.
+ *                                              Default 'The name is how it appears on your site'.
+ *     @type string $slug_field_description     Description for the Slug field on Edit Tags screen.
+ *                                              Default 'The &#8220;slug&#8221; is the URL-friendly version
+ *                                              of the name. It is usually all lowercase and contains
+ *                                              only letters, numbers, and hyphens'.
+ *     @type string $parent_field_description   Description for the Parent field on Edit Tags screen.
+ *                                              Default 'Assign a parent term to create a hierarchy.
+ *                                              The term Jazz, for example, would be the parent
+ *                                              of Bebop and Big Band'.
+ *     @type string $desc_field_description     Description for the Description field on Edit Tags screen.
+ *                                              Default 'The description is not prominent by default;
+ *                                              however, some themes may show it'.
  *     @type string $edit_item                  Default 'Edit Tag'/'Edit Category'.
  *     @type string $view_item                  Default 'View Tag'/'View Category'.
  *     @type string $update_item                Default 'Update Tag'/'Update Category'.
@@ -644,18 +659,23 @@ function get_taxonomy_labels( $tax ) {
 		$tax->labels['not_found'] = $tax->no_tagcloud;
 	}
 
+	$name_field_description   = __( 'The name is how it appears on your site.' );
+	$slug_field_description   = __( 'The &#8220;slug&#8221; is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens.' );
+	$parent_field_description = __( 'Assign a parent term to create a hierarchy. The term Jazz, for example, would be the parent of Bebop and Big Band.' );
+	$desc_field_description   = __( 'The description is not prominent by default; however, some themes may show it.' );
+
 	$nohier_vs_hier_defaults = array(
 		'name'                       => array( _x( 'Tags', 'taxonomy general name' ), _x( 'Categories', 'taxonomy general name' ) ),
-		'name_description'           => array( __( 'The name is how it appears on your site.' ), __( 'The name is how it appears on your site.' ) ),
 		'singular_name'              => array( _x( 'Tag', 'taxonomy singular name' ), _x( 'Category', 'taxonomy singular name' ) ),
 		'search_items'               => array( __( 'Search Tags' ), __( 'Search Categories' ) ),
 		'popular_items'              => array( __( 'Popular Tags' ), null ),
 		'all_items'                  => array( __( 'All Tags' ), __( 'All Categories' ) ),
 		'parent_item'                => array( null, __( 'Parent Category' ) ),
 		'parent_item_colon'          => array( null, __( 'Parent Category:' ) ),
-		'parent_description'         => array( null, __( 'Assign a parent term to create a hierarchy. The term Jazz, for example, would be the parent of Bebop and Big Band.' ) ),
-		'slug_description'           => array( __( 'The &#8220;slug&#8221; is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens.' ), __( 'The &#8220;slug&#8221; is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens.' ) ),
-		'description_description'    => array( __( 'The description is not prominent by default; however, some themes may show it.' ), __( 'The description is not prominent by default; however, some themes may show it.' ) ),
+		'name_field_description'     => array( $name_field_description, $name_field_description ),
+		'slug_field_description'     => array( $slug_field_description, $slug_field_description ),
+		'parent_field_description'   => array( null, $parent_field_description ),
+		'desc_field_description'     => array( $desc_field_description, $desc_field_description ),
 		'edit_item'                  => array( __( 'Edit Tag' ), __( 'Edit Category' ) ),
 		'view_item'                  => array( __( 'View Tag' ), __( 'View Category' ) ),
 		'update_item'                => array( __( 'Update Tag' ), __( 'Update Category' ) ),
diff --git a/wp-includes/version.php b/wp-includes/version.php
index b7dc1384b9..7a54961c41 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-alpha-52162';
+$wp_version = '5.9-alpha-52163';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.