Admin: clarify the "Add New" links for better accessibility

[afercia]

In the admin menu and in some of the admin pages, various links use "Add New" as link text. While these links are clarified by the visual context, they are not so meaningful when read out of context.

Assistive technologies provide tools to list all the links in a page and dedicated keyboard shortcuts to navigate through links. In this scenario, a link that only says "Add New" isn't sufficiently clear: users won't have a clue what the purpose and destination of the link is.

One more scenario: users who use speech input software (e.g. Dragon) will voice a command like "Click add new". However, in a standard WordPress page there are at least 5 "Add New" links. The software will display choices to users (usually by displaying numbers close to all the links that it has identified as "Add New"). Then, users will have to:

• visually identify on the screen the highlighted links
• voice an additional command, e.g. "Choose 3"

This makes the process inefficient and time consuming.

Ideally, all these links should be self-explanatory and provide more context by adding the "what" new is in the text link. For example:

• Add New Post
• Add New Media
• Add New Page
• Add New Plugin
• Add New User

[afercia]

VoiceOver links list

[afercia]

In the screenshot above, the VoiceOver links list showing some of the "Add New" links.

As mentioned previously, this applies also to the "Add New" links within the various pages, e.g. in wp-admin/edit.php and also the ones on multisite.

Related: #47124 and #47012.

[afercia]

Discussed during today's accessibility bug scrub and agreed this is something that should be addressed, especially for speech recognition software users.

[gonzomir]

I've submitted a patch that updates all "Add New" links (that I could find in the source) together with "Add Existing" links for users and some comments, theme readmes that reference these links. I'm not sure though that my approach for the post types "Add New" menu items is the best one.

[alexstine]

Refresh.

[alexstine]

Refreshed the patch.

https://core.trac.wordpress.org/raw-attachment/ticket/47125/47125-patch.2.diff

[afercia]

Just noting that if this proposed change gets approved we could consider to not use the _x() translation function any longer. Specifying the context would be pointless as the new strings are already in context. For example:

_x( 'Add New Link', 'link' )

The provided context 'link' is not necessary, as the string is already clear enough.

__( 'Add New Link' )

would be simpler and cleaner.

[alexstine]

Change _x() to ().

[alexstine]

Updated the patch to use __() vs. _x().

https://core.trac.wordpress.org/raw-attachment/ticket/47125/47125-patch.3.diff

[afercia]

Thanks for updating the patch. While testing, I noticed there are still around 30 occurrences of 'Add New' in the codebase that would need to be checked. A few of them are in comments or help text but they should be updated as well.

Also, making the search case sensitive I found a couple places where the letter 'n' of the word 'new' is lowercase:

__( 'Add new Pattern' )
_e( 'Add new Comment' )

This is inconsistent with the well established pattern in WordPress, where all similar strings use title case for the word 'New', for example:

__( 'Add New Template' )

'Add new Pattern' was recently Introduced in [56030]

Adding a screenshot to illustrate some examples of what the current patch does.

[afercia]

Related GitHub issue on the Gutenberg repository: ​https://github.com/WordPress/gutenberg/issues/53984

[alexstine]

More replacements.

[alexstine]

Probably not perfect, but I think this moves us closer.

https://core.trac.wordpress.org/attachment/ticket/47125/47125-patch.4.diff

Anything I missed this go around @afercia?

Thanks.

[marybaum]

Love this! @afercia would you review the design so this ticket could land in 6.4?

[swissspidy]

Looking at 47125-patch.4.diff​, I'd slightly adjust the change to the docblock of get_post_type_labels()

Right now it says "Default is 'Add New Type' for both hierarchical and non-hierarchical types." and "matching your post type. Example: __( 'Add New Type' );."

I would change this to "Default is 'Add New Post' / 'Add New Page'" and "matching your post type. Example: __( 'Add New Product' );.", respectively.

Also, that change warrants a mentioned in a dev-note somewhere so developers update labels in their plugins.

[alexstine]

Doc block improvement.

[alexstine]

Updated: https://core.trac.wordpress.org/raw-attachment/ticket/47125/47125-patch.5.diff

[joedolson]

Removed a few translator comments that are no longer needed with the removal of _x() calls. Also restored the 'textdomain' argument in the get_post_type_labels() docblock, as that is still an important instruction for extenders.

[joedolson]

Remove translators comments & restore textdomain arg

[joedolson]

I'm don't see that this requires design feedback. These are all text changes. I don't see anything design wise that requires comment.

I'm marking this for commit. There may be further strings that would merit changing, but I don't think those should stop this from getting resolved; we can always add follow-up commits. I searched the code and there's nothing obvious remaining.

Trac ticket: https://core.trac.wordpress.org/ticket/47125

[joedolson]

In 56515:

Administration: Add improved context for add new links.

Consistently expand Add New links to include the type of content to add. Improve consistency of text casing to use initial caps throughout.

Props afercia, gonzomir, alexstine, swissspidy, joedolson.
Fixes #47125.

[SergeyBiryukov]

In 56519:

Docs: Add a @since note for add_new labels change in get_post_type_labels().

Includes removing an obsolete recommendation to use a gettext context matching the post type for disambiguation, which would be redundant with the new labels, as they already include the type of content.

Follow-up [14571], [56515].

See #47125.

[webcommsat]

@swissspidy following up your comment above on a mention in dev note for plugin devs to update their labels, does something on this need to go in the email to plugin devs too that Marcomms are drafting (cc @meher )?

Is there a paragraph or sentence on the change that could be used in a Miscellaneous dev note, assuming from the discussion above it does not need a single dev note? It may be that accessibility are including this in a dev note on accessibility areas? @joedolson @afercia

Thank you everyone and for bringing this fix.

[swissspidy]

@webcommsat Yes this can go in a Miscellaneous dev note as it does not need a dedicated one. No need for a special mention in the plugins email, as those emails just link to the field guide anyway.

A paragraph like this should work:

In WordPress 6.4, the default values for the `add_new` label changed to include the type of content. This matches `add_new_item` and provides more context for better accessibility.
The default value is 'Add New Type' for both hierarchical and non-hierarchical types.
If you've previously used a label such as `'add_new' => _x( 'Add New', 'Book', 'my-plugin' )`, you are encouraged to change it to `'add_new' => __( 'Add New Book', 'my-plugin' )`.

[dilip2615]

[1]. Modify WordPress Admin Menu Items
For the admin menu, you can hook into the admin_menu action to change the labels of the "Add New" menu items. Here's an example:

function customize_admin_menu_labels() {
    global $menu, $submenu;

    // Update "Posts" submenu
    if (isset($submenu['edit.php'])) {
        foreach ($submenu['edit.php'] as &$item) {
            if ($item[0] == 'Add New') {
                $item[0] = 'Add New Post';
            }
        }
    }

    // Update "Media" submenu
    if (isset($submenu['upload.php'])) {
        foreach ($submenu['upload.php'] as &$item) {
            if ($item[0] == 'Add New') {
                $item[0] = 'Add New Media';
            }
        }
    }

    // Update "Pages" submenu
    if (isset($submenu['edit.php?post_type=page'])) {
        foreach ($submenu['edit.php?post_type=page'] as &$item) {
            if ($item[0] == 'Add New') {
                $item[0] = 'Add New Page';
            }
        }
    }

    // Update "Plugins" submenu
    if (isset($submenu['plugins.php'])) {
        foreach ($submenu['plugins.php'] as &$item) {
            if ($item[0] == 'Add New') {
                $item[0] = 'Add New Plugin';
            }
        }
    }

    // Update "Users" submenu
    if (isset($submenu['users.php'])) {
        foreach ($submenu['users.php'] as &$item) {
            if ($item[0] == 'Add New') {
                $item[0] = 'Add New User';
            }
        }
    }
}
add_action('admin_menu', 'customize_admin_menu_labels');

[2]. Modify Admin Page Links

If there are "Add New" links within admin pages (e.g., on the Posts, Pages, Media, etc.), you can use a script to update these links dynamically. Here's a basic example using jQuery:

function customize_admin_add_new_links() {
    ?>
    <script type="text/javascript">
        jQuery(document).ready(function($) {
            // Update the "Add New" links
            $('a.add-new-h2').each(function() {
                var href = $(this).attr('href');
                if (href.includes('post-new.php?post_type=post')) {
                    $(this).text('Add New Post');
                } else if (href.includes('post-new.php?post_type=page')) {
                    $(this).text('Add New Page');
                } else if (href.includes('post-new.php?post_type=attachment')) {
                    $(this).text('Add New Media');
                } else if (href.includes('plugin-install.php')) {
                    $(this).text('Add New Plugin');
                } else if (href.includes('user-new.php')) {
                    $(this).text('Add New User');
                }
            });
        });
    </script>
    <?php
}
add_action('admin_footer', 'customize_admin_add_new_links');