An Introduction to the Gettext Filter

Finding a plugin or theme for your WordPress site that meets all your requirements can be a challenge. Many may come close but still need adjustments or customizations. Additionally, as a developer, it’s vital to ensure your code is flexible enough to support users from around the globe. 

Fortunately, there are some features of WordPress core that can help you adapt certain elements of your site. This enables you to customize button or label text rather than abandoning an otherwise useful plugin, or even prepare your site for translation.  

In this article, we’ll provide a better understanding of the gettext filter, including how it works with your site’s translation process. There’s a lot to cover, so let’s dive right in! 

What is Gettext? 

The gettext filter enables you to modify text elements on your WordPress site. It’s best understood through an example.

Say your comment form has two fields: “Name” and “Email”. If you would rather they read “First Name” and “Email Address”, you could use the gettext filter to modify them instead of having to manually replace every instance of each term in your theme files.

The gettext filter only works if your site has been prepared for translation. Therefore, before we dive into how you can use it to customize text, we have to discuss how to internationalize your code. 

A few terms to understand before proceeding include: 

• Internationalization (i18n). This means your WordPress code has been prepared for translation into other languages. 
• Localization (l10n). The process by which you can take i18n programming and localize your WordPress installation for use in a native language. 
• GNU gettext library. GNU is a free, open-source operating system. Its gettext library enables you to wrap text in strings of code, which can then be extracted for translation. 
• POT file: To execute extraction of the translatable strings created with gettext functions, Portable Object Template (POT) files are created.
• PO file: A tool such as Poedit uses a POT file to create Portable Object (PO) files that include the completed translations as well as the translatable strings. 
• MO file: A Machine Object (MO) file is created from a PO file. It resides in your plugin or theme directory and is delivered by your server if a translated version of your website is requested.

These elements all play roles in preparing WordPress products for translation, as you’ll see in the steps below.

Gettext and PHP for Translation

Below, we’ve explained the workflow for internationalizing a theme or plugin. Before experimenting with such changes, it’s recommended that you create a child theme to work with. This will protect your site from any potential disasters. 

Step 1:  Extract Text Strings as POT Files

The first thing you’ll want to do is check if your theme or plugin already includes POT files. If not, you’ll need to auto-generate them, manually create them with Terminal, or use an application recommended by WordPress that we mentioned earlier called Poedit: 

The Pro version offers a quick WordPress feature for creating the files you need. However, you can still generate a POT file with a few extra clicks using the free app. 

To get started you’ll need to download and install Poedit, which will run on your desktop. Once you’ve done that, navigate to File > New. You’ll be prompted to select the language for your translation: 

You’ll then need to save your new project before proceeding. Next, you’ll have the option to update an existing POT file or Extract from sources: 

If needed, you can also start with a blank POT file, then alter your text strings in Poedit. Alternatively, you can search Glotpress for existing plugin and theme files to use. However, for this example, let’s assume you’ll need to use the other option. 

Once you click on Extract from sources you’ll have three tabs of settings to configure: 

You will need to set the paths for the sources of your text strings. You can also exclude certain paths. Then, you’ll want to configure your translation properties: 

This is where you’ll name your project and customize settings for plurals and other language-specific elements. Lastly, you can use the Sources Keywords tab to complete the setup for your POT file:

When you click on the plus sign, you’ll be able to add gettext keywords to complete your translation setup. You will also be able to see and search text strings from your source files.

Step 2: Create a Portable Object (PO) File 

Next, you’ll need to convert your POT file into a PO file for each language you wish to add. If you’re not translating your theme or plugin and only plan to use the gettext filter for English to English substitutions, set both languages (source and translation) to English. 

If you navigate to Catalog > Update from POT File in Poedit, you can choose the file you want to translate: 

Next, the file will go through an extraction process during which all the translatable strings will be brought into Poedit. This creates the PO file. You’ll want to name it to match your other files for this project. 

Then, click on Create New Translation at the bottom of the list of text strings to begin making your changes: 

To alter the text from English to English, just click on the string you want to change and use the Translation window below Source text to type in the substituted word: 

Complete this process for any of the text you want to change throughout your theme or plugin. Next, you’ll create the last of the three necessary files. 

Step 3: Convert to Machine Object (MO) Files

Up until now, you’ve been taking steps to create programming instructions regarding your translations. Now, you’ll need to convert each PO file so it can be read by the server and deliver the desired text to visitors. 

Depending on how you go through the Poedit workflow, an MO file may already have been created in your theme’s Languages folder. If not, navigate to File > Compile to MO: 

Now you should have the components you need to execute features made possible by the gettext filter in WordPress.

When is the WordPress Gettext Filter Useful? 

Although the process we’ve described above could help you translate your site into many languages, that’s not the purpose of the gettext filter. In other words, you wouldn’t want to use this hook to turn English text into Spanish.

Rather, this is more of a design functionality you can use to modify default text added to your site by a plugin or theme, such as through: 

• Label customization
• Button text changes
• Heading alterations

This process can be used to customize any text that is deemed translatable in your website files. To provide another example, if your theme has preset buttons that read “Buy Now” but your site needs them to read “Subscribe”, gettext is the filter that can make that change a reality.

It’s important to note that using gettext too frequently can have a negative impact on your website’s performance. This is additional code that must run every time your site is loaded, so use it sparingly to avoid decreased page speed.

Spread Your Message with WP Engine 

Deciding whether or not to use plugins or create manual code changes to your website can be challenging. That’s why having the best developer resources on hand is key. Armed with expert, professional support from WP Engine, you’ll have what you need to create a highly customized website. 

Check out our managed dedicated WordPress hosting plans for your next project. We’ve got your server maintenance covered so you can innovate with ease!