Modify text strings using Say What? plugin
WordPress plugins and themes are tools that allow you to customize the functionality and look of your WordPress website. Many of them include settings and configuration options that allow you to tweak things to your needs. For example, Easy Digital Downloads gives you the ability to control the email subject and heading of the Purchase Receipt email sent to customers after a purchase:
While these types of settings are convenient when you need to modify text that is included in a plugin or theme, it isn't feasible to include such settings for all text strings. Some text strings, whether displayed to users, or only displaying in the WordPress admin, are assumed to be sufficient for viewers and cannot be easily modified.
This is where the Say What? WordPress plugin comes in handy. Say What? takes advantage of a WordPress standard that encourages plugin and theme developers to make all text strings "translation-ready." When a text string is translation-ready, that means with the proper WordPress configuration, the plugin or theme can be translated to a different language.
Say What? has the ability target those translation-ready text strings individually and modify them as needed.
Using Say What? to modify a text string
Let's look at a simple example for how to modify a text string using the Say What? plugin.
When a product is added to the cart in Easy Digital Downloads, and the customer proceeds to the checkout page, the checkout cart is displayed with a list of products that the customer has added to the cart.
Notice the "Item Name," "Item Price," and "Actions" headings that display above the columns in the checkout cart. Those are text strings included in Easy Digital Downloads. However, there are no settings to change that text. So we'll use Say What? to modify the "Item Name" text using the following steps.
2. Once activated, go to Tools -> Text changes in your WordPress dashboard and click the Add New button at the top of the page.
3. You will be presented with four text fields: Original string, Text domain, Text context, and Replacement string.
- Original string - This field is for the text you are attempting to change. In this case, we want to change the "Item Name" text string, so that is exactly what you would enter into the field. Note: This field is case-sensitive. That means you must enter the text exact as it is displayed. "Item Name" and "item name" are not the same text string.
- Text domain - This field requires a unique identifier that each plugin or theme must have. For Easy Digital Downloads, the text domain is
easy-digital-downloads. If you need assistance finding the text domain for another plugin or theme, please contact the developer.
- Text context - This field isn't always required. Sometimes, two or more text strings in a single plugin or theme are exactly the same. When this happens, developers will typically provide context for each text string that helps identify where each particular string is used. In most cases, this field can be left blank.
- Replacement string - This field is your playground. The text you place in the Original string field will be replaced by whatever you put in this field.
4. Save your new Text change and check the results.
Here's a look at a text change the fits our example work:
With that text change added, we can expect "Item Name" to be replaced by "My Custom Text" on the checkout cart.
Troubleshooting & common issues
There are times when using Say What? is a little more complicated than the example above. If you've created a new text change and it is not working properly, there are a few different things to check for.
Make sure your Original string value uses the same case pattern as the text string you are trying to modify.
My Text String is not the same as
my text string.
Translation-ready strings in WordPress may be wrapped in PHP code that allows parts of the text to be replaced by placeholders.
For example, Easy Digital Downloads displays an error on the checkout page if a customer tries to complete a purchase using an email address that belongs to another customer. The following message will be displayed:
The email address firstname.lastname@example.org is already in use.
While that looks like a normal text string to the customer, the actual text string uses a PHP placeholder to allow the email address to hold a different value based on the email address the customer is attempting to use. So the actual text string looks like this:
The email address %s is already in use.
As you can see,
%s is the placeholder for the email address. When you create your text change in Say What?, the Original string field requires that you include the text string as-is, meaning your value may include one or more PHP placeholders.
Text context required
It's not uncommon for two different text strings to be exactly the same. When this occurs, developers are encouraged to provide a context that explains where each text string is used in order to differentiate one from the other.
If you were to search a plugin or theme's code base for a specific text string, for example, the text string "Save" in a particular plugin, you may find that this exact text string is used in three different places. That means without context, modifying the text string will cause changes in all three locations. To avoid that, you may notice a translation-ready text string in the code base that looks like this:
__( 'Save', 'the button for saving plugin settings', 'text-domain');
This text string provides a context of
the button for saving plugin settings. When you create your text change in Say What?, make sure you enter that exact value into the Text context field.
Notes & tips
Sometimes it will take a bit of work to track down a text string. The text string itself may not always be the same as the text you see displayed on your website.
A quick way to find the exact text string you are looking for is to look in the plugin or themes root folder for a languages directory, and then search that directory for a file ending with .pot. This file should include a complete list of translation-ready strings provided by the plugin or theme. Strategically search the list for your string. For example, you may want to search "already in use" when looking for the string from our Placeholders example.
If you cannot find a text string, contact support for the plugin or theme and ask for help tracking it down. It could be that you simply overlooked it, or that the text string isn't translation-ready.