ESLint: Add rule to prevent usage of the word 'sidebar' in translatable strings

[im3dabasia]

Related comment: #61499 (comment)

What?

This PR introduces a new ESLint rule to prevent the use of the term "sidebar" in user-facing strings throughout the codebase. The rule aims to ensure that more generic and accessible terms like "panel" are used in place of "sidebar."

Why?

The term "sidebar" is problematic for blind and low-vision users, as it relies on spatial concepts that are irrelevant to them. Additionally, the term can be misleading on smaller screens where "sidebars" are often full-width overlays. This change is necessary to align with the accessibility guidelines. It ensures consistency in user-facing language across WordPress projects.

How?

The PR implements an ESLint rule that flags occurrences of the word "sidebar" in translatable strings, helping developers avoid its usage in user-facing content. The rule is added to the .eslintrc.js configuration to prevent new instances of this term from being introduced.

Testing Instructions

1. Change any word inside any translation ready functions to "sidebar" in any file.
2. Check if your IDE raises an ESLint error with the message: "Avoid using the word 'sidebar' in translatable strings."

Screencast

Screen.Recording.2025-01-27.at.4.03.49.PM.mov

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: im3dabasia <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: afercia <[email protected]>
Co-authored-by: swissspidy <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[im3dabasia]

Hi @swissspidy,

When you have a moment, could you please review my PR.

cc: @afercia

[tyxla]

Looks good overall 👍

[im3dabasia]

The lint checks are failing, but the ones related to this PR possibly include... I'll put together a comprehensive set of suggestions so we can move forward.

Edit: I see some false positives being raised, especially in URLs, such as /sidebar-panel-is-here. I think a regex update should solve this.

gutenberg/packages/edit-site/src/components/add-new-template/add-custom-generic-template-modal-content.js

Lines 45 to 56 in be0f32a

	<TextControl
	__next40pxDefaultSize
	__nextHasNoMarginBottom
	label={ __( 'Name' ) }
	value={ title }
	onChange={ setTitle }
	placeholder={ defaultTitle }
	disabled={ isBusy }
	help={ __(
	'Describe the template, e.g. "Post with sidebar". A custom template can be manually applied to any post or page.'
	) }
	/>

gutenberg/packages/edit-site/src/components/welcome-guide/page.js

Lines 53 to 64 in be0f32a

	content: (
	<>
	<h1 className="edit-site-welcome-guide__heading">
	{ heading }
	</h1>
	<p className="edit-site-welcome-guide__text">
	{ __(
	'It’s now possible to edit page content in the site editor. To customise other parts of the page like the header and footer switch to editing the template using the settings sidebar.'
	) }
	</p>
	</>
	),

gutenberg/packages/edit-widgets/src/components/sidebar/widget-areas.js

Lines 34 to 38 in be0f32a

	if ( ! selectedWidgetArea ) {
	description = __(
	'Widget Areas are global parts in your site’s layout that can accept blocks. These vary by theme, but are typically parts like your Sidebar or Footer.'
	);
	} else if ( selectedWidgetAreaId === 'wp_inactive_widgets' ) {

gutenberg/packages/editor/src/components/page-attributes/parent.js

Lines 279 to 294 in be0f32a

	<p>
	{ createInterpolateElement(
	__(
	'They also show up as sub-items in the default navigation menu. <a>Learn more.</a>'
	),
	{
	a: (
	<ExternalLink
	href={ __(
	'https://wordpress.org/documentation/article/page-post-settings-sidebar/#page-attributes'
	) }
	/>
	),
	}
	) }
	</p>

gutenberg/packages/editor/src/components/post-excerpt/index.js

Lines 78 to 90 in be0f32a

	help={
	! shouldUseDescriptionLabel ? (
	<ExternalLink
	href={ __(
	'https://wordpress.org/documentation/article/page-post-settings-sidebar/#excerpt'
	) }
	>
	{ __( 'Learn more about manual excerpts' ) }
	</ExternalLink>
	) : (
	__( 'Write a description' )
	)
	}

gutenberg/packages/editor/src/components/post-template/create-new-template-modal.js

Lines 120 to 131 in be0f32a

	<TextControl
	__next40pxDefaultSize
	__nextHasNoMarginBottom
	label={ __( 'Name' ) }
	value={ title }
	onChange={ setTitle }
	placeholder={ DEFAULT_TITLE }
	disabled={ isBusy }
	help={ __(
	'Describe the template, e.g. "Post with sidebar". A custom template can be manually applied to any post or page.'
	) }
	/>

gutenberg/packages/editor/src/components/post-url/index.js

Lines 90 to 106 in be0f32a

	<p className="editor-post-url__intro">
	{ createInterpolateElement(
	__(
	'<span>Customize the last part of the Permalink.</span> <a>Learn more.</a>'
	),
	{
	span: <span id={ postUrlSlugDescriptionId } />,
	a: (
	<ExternalLink
	href={ __(
	'https://wordpress.org/documentation/article/page-post-settings-sidebar/#permalink'
	) }
	/>
	),
	}
	) }
	</p>

gutenberg/packages/editor/src/components/preferences-modal/index.js

Lines 87 to 94 in be0f32a

	<PreferenceToggleControl
	scope="core"
	featureName="showListViewByDefault"
	help={ __(
	'Opens the List View sidebar by default.'
	) }
	label={ __( 'Always open List View' ) }
	/>

gutenberg/packages/editor/src/components/sidebar/header.js

Lines 19 to 27 in be0f32a

	const { documentLabel } = useSelect( ( select ) => {
	const { getPostTypeLabel } = select( editorStore );
	return {
	documentLabel:
	// translators: Default label for the Document sidebar tab, not selected.
	getPostTypeLabel() || _x( 'Document', 'noun, sidebar' ),
	};
	}, [] );

gutenberg/packages/editor/src/components/sidebar/index.js

Lines 104 to 107 in be0f32a

	title={
	/* translators: button label text should, if possible, be under 16 characters. */
	_x( 'Settings', 'sidebar button label' )
	}

gutenberg/packages/fields/src/fields/parent/parent-edit.tsx

Lines 323 to 337 in be0f32a

	{ createInterpolateElement(
	__(
	'They also show up as sub-items in the default navigation menu. <a>Learn more.</a>'
	),
	{
	a: (
	<ExternalLink
	href={ __(
	'https://wordpress.org/documentation/article/page-post-settings-sidebar/#page-attributes'
	) }
	children={ undefined }
	/>
	),
	}
	) }

[im3dabasia]

Hi @afercia , @swissspidy , @tyxla ,

I’d appreciate your input once again in suggesting alternative strings for the following:

For now, I have replaced "sidebar" with "panel," but if you have any alternative suggestions for any of these, I’d be happy to update them.

1. 'Describe the template, e.g. "Post with sidebar". A custom template can be manually applied to any post or page.'
2. 'It’s now possible to edit page content in the site editor. To customise other parts of the page like the header and footer switch to editing the template using the settings sidebar.'
3. 'Widget Areas are global parts in your site’s layout that can accept blocks. These vary by theme, but are typically parts like your Sidebar or Footer.'
4. 'Describe the template, e.g. "Post with sidebar". A custom template can be manually applied to any post or page.'
5. 'Opens the List View sidebar by default.'
6. _x( 'Document', 'noun, sidebar' )
7. _x( 'Settings', 'sidebar button label' )

Additionally, we have URLs inside translation functions( 4 instances ), such as:

__('https://wordpress.org/documentation/article/page-post-settings-sidebar/#page-attributes')

We could add an ESLint ignore here, but I don’t think that’s the best solution. A better approach would be to update the regex.

The previous regex worked well, but it caused false positives for URLs because \b only checks for alphanumeric characters, and a hyphen (-) is not considered alphanumeric. This led to unintended matches.

I have updated the regex to ensure that "sidebar" is only flagged when it is a standalone word and not part of another word (e.g., "no-sidebar").

Updated regex:

{
	selector:
		'CallExpression[callee.name=/^(__|_x|_n|_nx)$/] > Literal[value=/(?<![-\\w])sidebar(?![-\\w])/i]',
	message:
		"Avoid using the word 'sidebar' in translatable strings. Consider using 'panel' instead.",
}

I have updated the PR with this new regex. Let me know your thoughts! @swissspidy

[swissspidy]

New regex looks good at first glance, seems to nicely prevent false positives.

I don't think we should change the instances where sidebar refers to a theme template part ("post with sidebar", "sidebar or footer", ...), as in that context the sidebar is a pretty common term.

Curious what others say though.

[afercia]

I'd agree with @swissspidy that the only occurrences to change should be the ones in the editor UI.

[swissspidy]

Then I'd say for the other instances let's ignore the eslint errors & add an explanatory comment why it's disabled

[im3dabasia]

Hi @afercia and @swissspidy,
I believe the changes have been made, and the PR is now ready. When you have a moment, I’d appreciate it if you could check the latest changes.

Hopefully, it can be merged into trunk soon. Thanks!

[im3dabasia]

Hi @afercia and @swissspidy,
Since the PR has been approved, I believe we can proceed with merging it now. Let me know if anything else is needed. Thanks!