Improve public-facing texts and labels (#7045)

We noticed that oftentimes our labels and text tend to be overly technical or unclear. We decided to do a bulk pass to improve the readability to non-technical users.
woocommerce · Sep 12, 2022 · d4e3247 · d4e3247
1 parent 00a1174
commit d4e3247
Show file tree

Hide file tree

Showing 59 changed files with 90 additions and 221 deletions.
diff --git a/assets/js/atomic/blocks/product-elements/category-list/constants.tsx b/assets/js/atomic/blocks/product-elements/category-list/constants.tsx
@@ -12,6 +12,6 @@ export const BLOCK_ICON: JSX.Element = (
 	<Icon icon={ archive } className="wc-block-editor-components-block-icon" />
 );
 export const BLOCK_DESCRIPTION: string = __(
-	'Display a list of categories belonging to a product.',
+	'Display the list of categories that are assigned to a product.',
 	'woo-gutenberg-products-block'
 );
diff --git a/assets/js/atomic/blocks/product-elements/image/edit.js b/assets/js/atomic/blocks/product-elements/image/edit.js
@@ -74,7 +74,7 @@ const Edit = ( { attributes, setAttributes, context } ) => {
 							'woo-gutenberg-products-block'
 						) }
 						help={ __(
-							'Overlay a "sale" badge if the product is on-sale.',
+							'Display a “sale” badge if the product is on-sale.',
 							'woo-gutenberg-products-block'
 						) }
 						checked={ showSaleBadge }

diff --git a/assets/js/atomic/blocks/product-elements/tag-list/constants.js b/assets/js/atomic/blocks/product-elements/tag-list/constants.js
@@ -12,6 +12,6 @@ export const BLOCK_ICON = (
 	<Icon icon={ tag } className="wc-block-editor-components-block-icon" />
 );
 export const BLOCK_DESCRIPTION = __(
-	'Display a list of tags belonging to a product.',
+	'Display the list of tags that are assigned to a product.',
 	'woo-gutenberg-products-block'
 );
diff --git a/assets/js/base/context/providers/add-to-cart-form/form-state/index.js b/assets/js/base/context/providers/add-to-cart-form/form-state/index.js
@@ -245,7 +245,7 @@ export const AddToCartFormStateContextProvider = ( {
 						const message =
 							data.processingResponse?.message ||
 							__(
-								'Something went wrong. Please contact us to get assistance.',
+								'Something went wrong. Please contact us for assistance.',
 								'woo-gutenberg-products-block'
 							);
 						createErrorNotice( message, {

diff --git a/assets/js/base/context/providers/add-to-cart-form/form/submit/index.js b/assets/js/base/context/providers/add-to-cart-form/form/submit/index.js
@@ -101,7 +101,7 @@ const FormSubmit = () => {
 						} else {
 							createErrorNotice(
 								__(
-									'Something went wrong. Please contact us to get assistance.',
+									'Something went wrong. Please contact us for assistance.',
 									'woo-gutenberg-products-block'
 								),
 								{

diff --git a/assets/js/base/context/providers/cart-checkout/checkout-processor.js b/assets/js/base/context/providers/cart-checkout/checkout-processor.js
@@ -257,7 +257,7 @@ const CheckoutProcessor = () => {
 							),
 							errorResponse?.message ??
 								__(
-									'Something went wrong.',
+									'Something went wrong. Please contact us for assistance.',
 									'woo-gutenberg-products-block'
 								)
 						),

diff --git a/assets/js/base/context/providers/cart-checkout/checkout-state/index.tsx b/assets/js/base/context/providers/cart-checkout/checkout-state/index.tsx
@@ -265,7 +265,7 @@ export const CheckoutStateProvider = ( {
 							const message =
 								data.processingResponse?.message ||
 								__(
-									'Something went wrong. Please contact us to get assistance.',
+									'Something went wrong. Please contact us for assistance.',
 									'woo-gutenberg-products-block'
 								);
 							createErrorNotice( message, {

diff --git a/assets/js/base/context/providers/cart-checkout/checkout-state/utils.ts b/assets/js/base/context/providers/cart-checkout/checkout-state/utils.ts
@@ -53,7 +53,7 @@ export const getPaymentResultFromCheckoutResponse = (
 		response.data.status > 299
 	) {
 		paymentResult.message = __(
-			'Something went wrong. Please contact us to get assistance.',
+			'Something went wrong. Please contact us for assistance.',
 			'woo-gutenberg-products-block'
 		);
 	}

diff --git a/assets/js/blocks/active-filters/active-attribute-filters.tsx b/assets/js/blocks/active-filters/active-attribute-filters.tsx
@@ -98,7 +98,7 @@ const ActiveAttributeFilters = ( {
 					if ( index > 0 && operator === 'and' ) {
 						prefix = (
 							<span className="wc-block-active-filters__list-item-operator">
-								{ __( 'and', 'woo-gutenberg-products-block' ) }
+								{ __( 'All', 'woo-gutenberg-products-block' ) }
 							</span>
 						);
 					}

diff --git a/assets/js/blocks/active-filters/block.json b/assets/js/blocks/active-filters/block.json
@@ -2,7 +2,7 @@
 	"name": "woocommerce/active-filters",
 	"version": "1.0.0",
 	"title": "Active Product Filters",
-	"description": "Show the currently active product filters. Works in combination with the All Products and filters blocks.",
+	"description": "Display the currently active product filters.",
 	"category": "woocommerce",
 	"keywords": [ "WooCommerce" ],
 	"supports": {

diff --git a/assets/js/blocks/active-filters/index.tsx b/assets/js/blocks/active-filters/index.tsx
@@ -19,7 +19,7 @@ import { Attributes } from './types';
 registerBlockType( metadata, {
 	title: __( 'Active Product Filters', 'woo-gutenberg-products-block' ),
 	description: __(
-		'Show the currently active product filters. Works in combination with the All Products and filters blocks.',
+		'Display the currently active product filters.',
 		'woo-gutenberg-products-block'
 	),
 	icon: {

diff --git a/assets/js/blocks/attribute-filter/block.json b/assets/js/blocks/attribute-filter/block.json
@@ -2,7 +2,7 @@
 	"name": "woocommerce/attribute-filter",
 	"version": "1.0.0",
 	"title": "Filter by Attribute",
-	"description": "Allow customers to filter the grid by product attribute, such as color.",
+	"description": "Enable customers to filter the product grid by selecting one or more attributes, such as color.",
 	"category": "woocommerce",
 	"keywords": [ "WooCommerce" ],
 	"supports": {
@@ -48,7 +48,7 @@
 		},
 		"selectType": {
 			"type": "string",
-			"default": "multiple" 
+			"default": "multiple"
 		},
 		"isPreview": {
 			"type": "boolean",

diff --git a/assets/js/blocks/attribute-filter/block.tsx b/assets/js/blocks/attribute-filter/block.tsx
@@ -495,7 +495,7 @@ const AttributeFilterBlock = ( {
 				<Notice status="warning" isDismissible={ false }>
 					<p>
 						{ __(
-							'The selected attribute does not have any term assigned to products.',
+							'There are no products with the selected attributes.',
 							'woo-gutenberg-products-block'
 						) }
 					</p>

diff --git a/assets/js/blocks/attribute-filter/edit.tsx b/assets/js/blocks/attribute-filter/edit.tsx
@@ -176,17 +176,6 @@ const Edit = ( { attributes, setAttributes, debouncedSpeak }: EditProps ) => {
 							'Include product count',
 							'woo-gutenberg-products-block'
 						) }
-						help={
-							showCounts
-								? __(
-										'Show the product count with results.',
-										'woo-gutenberg-products-block'
-								  )
-								: __(
-										'Product count is hidden.',
-										'woo-gutenberg-products-block'
-								  )
-						}
 						checked={ showCounts }
 						onChange={ () =>
 							setAttributes( {
@@ -314,11 +303,11 @@ const Edit = ( { attributes, setAttributes, debouncedSpeak }: EditProps ) => {
 						help={
 							showFilterButton
 								? __(
-										'Products will only update when the button is pressed.',
+										'Products will only update when the button is clicked.',
 										'woo-gutenberg-products-block'
 								  )
 								: __(
-										'Products will update as options are selected.',
+										'Products will update as soon as attributes are selected.',
 										'woo-gutenberg-products-block'
 								  )
 						}
@@ -352,7 +341,7 @@ const Edit = ( { attributes, setAttributes, debouncedSpeak }: EditProps ) => {
 				'woo-gutenberg-products-block'
 			) }
 			instructions={ __(
-				'Display a list of filters based on a chosen attribute.',
+				'Display a list of filters based on the selected attributes.',
 				'woo-gutenberg-products-block'
 			) }
 		>
@@ -387,7 +376,7 @@ const Edit = ( { attributes, setAttributes, debouncedSpeak }: EditProps ) => {
 		setIsEditing( false );
 		debouncedSpeak(
 			__(
-				'Showing Filter by Attribute block preview.',
+				'Now displaying a preview of the Filter Products by Attribute block.',
 				'woo-gutenberg-products-block'
 			)
 		);
@@ -403,7 +392,7 @@ const Edit = ( { attributes, setAttributes, debouncedSpeak }: EditProps ) => {
 					'woo-gutenberg-products-block'
 				) }
 				instructions={ __(
-					'Display a list of filters based on a chosen attribute.',
+					'Display a list of filters based on the selected attributes.',
 					'woo-gutenberg-products-block'
 				) }
 			>

diff --git a/assets/js/blocks/attribute-filter/index.tsx b/assets/js/blocks/attribute-filter/index.tsx
@@ -19,7 +19,7 @@ import metadata from './block.json';
 registerBlockType( metadata, {
 	title: __( 'Filter by Attribute', 'woo-gutenberg-products-block' ),
 	description: __(
-		'Allow customers to filter the grid by product attribute, such as color.',
+		'Enable customers to filter the product grid by selecting one or more attributes, such as color.',
 		'woo-gutenberg-products-block'
 	),
 	icon: {

diff --git a/...ts/js/blocks/cart-checkout-shared/payment-methods/express-payment/cart-express-payment.js b/...ts/js/blocks/cart-checkout-shared/payment-methods/express-payment/cart-express-payment.js
@@ -66,7 +66,7 @@ const CartExpressPayment = () => {
 			</LoadingMask>
 			<div className="wc-block-components-express-payment-continue-rule wc-block-components-express-payment-continue-rule--cart">
 				{ /* translators: Shown in the Cart block between the express payment methods and the Proceed to Checkout button */ }
-				{ __( 'Or', 'woo-gutenberg-products-block' ) }
+				{ __( 'Any', 'woo-gutenberg-products-block' ) }
 			</div>
 		</>
 	);

diff --git a/assets/js/blocks/cart-checkout-shared/payment-methods/no-payment-methods/index.js b/assets/js/blocks/cart-checkout-shared/payment-methods/no-payment-methods/index.js
@@ -38,7 +38,7 @@ const NoPaymentMethodsPlaceholder = () => {
 		>
 			<span className="wc-block-checkout__no-payment-methods-placeholder-description">
 				{ __(
-					'Your store does not have any payment methods configured that support the checkout block. Once you have configured a compatible payment method it will be shown here.',
+					'Your store does not have any payment methods that support the Checkout block. Once you have configured a compatible payment method it will be displayed here.',
 					'woo-gutenberg-products-block'
 				) }
 			</span>

diff --git a/assets/js/blocks/cart-checkout-shared/payment-methods/payment-method-error-boundary.js b/assets/js/blocks/cart-checkout-shared/payment-methods/payment-method-error-boundary.js
@@ -24,7 +24,7 @@ class PaymentMethodErrorBoundary extends Component {
 
 		if ( hasError ) {
 			let errorText = __(
-				'This site is experiencing difficulties with this payment method. Please contact the owner of the site for assistance.',
+				'We are experiencing difficulties with this payment method. Please contact us for assistance.',
 				'woo-gutenberg-products-block'
 			);
 			if ( isEditor || CURRENT_USER_IS_ADMIN ) {

diff --git a/assets/js/blocks/cart/block.js b/assets/js/blocks/cart/block.js
@@ -74,7 +74,10 @@ const ScrollOnError = ( { scrollToTop } ) => {
 };
 const Block = ( { attributes, children, scrollToTop } ) => (
 	<BlockErrorBoundary
-		header={ __( 'Something went wrong…', 'woo-gutenberg-products-block' ) }
+		header={ __(
+			'Something went wrong. Please contact us for assistance.',
+			'woo-gutenberg-products-block'
+		) }
 		text={ __(
 			'The cart has encountered an unexpected error. If the error persists, please get in touch with us for help.',
 			'woo-gutenberg-products-block'

diff --git a/assets/js/blocks/cart/inner-blocks/cart-express-payment-block/edit.tsx b/assets/js/blocks/cart/inner-blocks/cart-express-payment-block/edit.tsx
@@ -27,7 +27,7 @@ const NoExpressPaymentMethodsPlaceholder = () => {
 		>
 			<span className="wp-block-woocommerce-checkout-express-payment-block-placeholder__description">
 				{ __(
-					"Your store doesn't have any Payment Methods that support the Express Checkout Block. If they are added, they will be shown here.",
+					'Your store does not have any payment methods that support the Express Checkout block. Once you have configured a compatible payment method, it will be displayed here.',
 					'woo-gutenberg-products-block'
 				) }
 			</span>

diff --git a/assets/js/blocks/checkout/block.tsx b/assets/js/blocks/checkout/block.tsx
@@ -145,7 +145,7 @@ const Block = ( {
 	return (
 		<BlockErrorBoundary
 			header={ __(
-				'Something went wrong…',
+				'Something went wrong. Please contact us for assistance.',
 				'woo-gutenberg-products-block'
 			) }
 			text={ createInterpolateElement(

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-billing-address-block/attributes.tsx b/assets/js/blocks/checkout/inner-blocks/checkout-billing-address-block/attributes.tsx
@@ -12,7 +12,7 @@ export default {
 	...formStepAttributes( {
 		defaultTitle: __( 'Billing address', 'woo-gutenberg-products-block' ),
 		defaultDescription: __(
-			'Enter the address that matches your card or payment method.',
+			'Enter the billing address that matches your payment method.',
 			'woo-gutenberg-products-block'
 		),
 	} ),

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-express-payment-block/edit.tsx b/assets/js/blocks/checkout/inner-blocks/checkout-express-payment-block/edit.tsx
@@ -27,7 +27,7 @@ const NoExpressPaymentMethodsPlaceholder = () => {
 		>
 			<span className="wp-block-woocommerce-checkout-express-payment-block-placeholder__description">
 				{ __(
-					"Your store doesn't have any Payment Methods that support the Express Checkout Block. If they are added, they will be shown here.",
+					'Your store does not have any payment methods that support the Express Checkout block. Once you have configured a compatible payment method, it will be displayed here.',
 					'woo-gutenberg-products-block'
 				) }
 			</span>

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/edit.tsx b/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/edit.tsx
@@ -65,7 +65,7 @@ export const Edit = ( {
 					>
 						<p className="wc-block-checkout__controls-text">
 							{ __(
-								'You currently have the following shipping integrations active.',
+								'The following shipping integrations are active on your store.',
 								'woo-gutenberg-products-block'
 							) }
 						</p>

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/block.json b/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/block.json
@@ -2,7 +2,7 @@
 	"name": "woocommerce/checkout-terms-block",
 	"version": "1.0.0",
 	"title": "Terms and Conditions",
-	"description": "Ensure customers agree to your terms and conditions and privacy policy.",
+	"description": "Ensure that customers agree to your Terms & Conditions and Privacy Policy.",
 	"category": "woocommerce",
 	"supports": {
 		"align": false,

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/edit.tsx b/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/edit.tsx
@@ -134,7 +134,7 @@ export const Edit = ( {
 				>
 					<p>
 						{ __(
-							"You don't seem to have a Terms and Conditions and/or a Privacy Policy pages setup.",
+							"You don't have any Terms and Conditions and/or Privacy Policy pages set up.",
 							'woo-gutenberg-products-block'
 						) }
 					</p>

diff --git a/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/test/edit.js b/assets/js/blocks/checkout/inner-blocks/checkout-terms-block/test/edit.js
@@ -59,7 +59,7 @@ describe( 'Edit', () => {
 		expect(
 			queryByText(
 				container,
-				"You don't seem to have a Terms and Conditions and/or a Privacy Policy pages setup."
+				"You don't have any Terms and Conditions and/or Privacy Policy pages set up."
 			)
 		).toBeInTheDocument();
 	} );

diff --git a/assets/js/blocks/classic-template/index.tsx b/assets/js/blocks/classic-template/index.tsx
@@ -71,20 +71,20 @@ const Edit = ( {
 					<p className="wp-block-woocommerce-classic-template__placeholder-warning">
 						<strong>
 							{ __(
-								'Attention: Do not remove this block!',
+								'Do not remove this block!',
 								'woo-gutenberg-products-block'
 							) }
 						</strong>{ ' ' }
 						{ __(
-							'Removal will cause unintended effects on your store.',
+							'Removing this will cause unintended effects on your store.',
 							'woo-gutenberg-products-block'
 						) }
 					</p>
 					<p>
 						{ sprintf(
 							/* translators: %s is the template title */
 							__(
-								'This is an editor placeholder for the %s. On your store this will be replaced by the template and display with your product image(s), title, price, etc. You can move this placeholder around and add further blocks around it to extend the template.',
+								'This is a placeholder for the %s. In your store it will display the actual product image, title, price, etc. You can move this placeholder around and add more blocks around it to customize the template.',
 								'woo-gutenberg-products-block'
 							),
 							templateTitle

diff --git a/assets/js/blocks/featured-items/featured-product/block.json b/assets/js/blocks/featured-items/featured-product/block.json
@@ -2,16 +2,11 @@
 	"name": "woocommerce/featured-product",
 	"version": "1.0.0",
 	"title": "Featured Product",
-	"description": "Visually highlight a product or variation and encourage prompt action.",
+	"description": "Highlight a product or variation.",
 	"category": "woocommerce",
-	"keywords": [
-		"WooCommerce"
-	],
+	"keywords": [ "WooCommerce" ],
 	"supports": {
-		"align": [
-			"wide",
-			"full"
-		],
+		"align": [ "wide", "full" ],
 		"html": false,
 		"color": {
 			"background": true,

diff --git a/assets/js/blocks/featured-items/featured-product/block.tsx b/assets/js/blocks/featured-items/featured-product/block.tsx
@@ -41,7 +41,7 @@ const CONTENT_CONFIG = {
 const EDIT_MODE_CONFIG = {
 	...GENERIC_CONFIG,
 	description: __(
-		'Visually highlight a product or variation and encourage prompt action',
+		'Highlight a product or variation.',
 		'woo-gutenberg-products-block'
 	),
 	editLabel: __(

diff --git a/assets/js/blocks/featured-items/inspector-controls.tsx b/assets/js/blocks/featured-items/inspector-controls.tsx
@@ -162,13 +162,13 @@ export const InspectorControls = ( {
 												} }
 											>
 												{ __(
-													'Choose “Cover” if you want the image to scale automatically to always fit its container.',
+													'Select “Cover” to have the image automatically fit its container.',
 													'woo-gutenberg-products-block'
 												) }
 											</span>
 											<span>
 												{ __(
-													'Note: by choosing “Cover” you will lose the ability to freely move the focal point precisely.',
+													'This may affect your ability to freely move the focal point of the image.',
 													'woo-gutenberg-products-block'
 												) }
 											</span>

diff --git a/assets/js/blocks/handpicked-products/edit-mode.tsx b/assets/js/blocks/handpicked-products/edit-mode.tsx
@@ -30,7 +30,7 @@ export const HandpickedProductsEditMode = (
 		setIsEditing( ! isEditing );
 		debouncedSpeak(
 			__(
-				'Showing Hand-picked Products block preview.',
+				'Now displaying a preview of the Hand-picked Products block.',
 				'woo-gutenberg-products-block'
 			)
 		);

diff --git a/assets/js/blocks/mini-cart/edit.tsx b/assets/js/blocks/mini-cart/edit.tsx
@@ -111,7 +111,7 @@ const Edit = ( { attributes, setAttributes }: Props ): ReactElement => {
 					>
 						<p>
 							{ __(
-								'Edit the appearance of your empty and filled mini cart contents.',
+								'Edit the appearance of the Mini Cart.',
 								'woo-gutenberg-products-block'
 							) }
 						</p>
-Original file line number
+Diff line change
@@ Expand Up / @@ -134,7 +134,7 @@ export const Edit = ( { @@
     				>
     					<p>
     						{ __(
-    							"You don't seem to have a Terms and Conditions and/or a Privacy Policy pages setup.",
+    							"You don't have any Terms and Conditions and/or Privacy Policy pages set up.",
     							'woo-gutenberg-products-block'
     						) }
     					</p>
@@ Expand Down @@