Localizing with the Phrase WordPress Translation Plugin

Localizing WordPress sites at scale just got a lot easier.

WordPress is absolutely massive: over 38% of all websites out there have the free content management system (CMS) as their foundation, and over 60% of CMS-based websites have chosen WordPress. Its architecture, ease-of-use, and massive ecosystem of plugins and themes are no doubt contributors to this colossal success. When it comes to localization, if you want a professional workflow that works for your team of managers, developers, and translators, you’ll do well to localize your WordPress site with the Phrase WordPress translation plugin.

In this article, we’ll build a little demo site to show you how easy it is to spin up a Phrase project, connect it to WordPress, and get to localizing your pages and posts in minutes. We’ll also add the popular Polylang plugin to our demo site to add a language switcher. Let’s get cooking.

🗒 Note » You need a Phrase Advanced Plan to work with the WordPress translation plugin. Try it for free for 14 days!

WordPress Environment Versions

We’re using the following stack and set of plugins to build our demo site (versions between parentheses):

  • PHP (7.4) — server-side language/processor
  • MySQL (8.0) — database
  • WordPress (5.5) — our CMS of choice
  • Phrase Plugin (1.0) — easily links our WordPress site with our Phrase account
  • Polylang (2.8) — handles URL, menu, and category localization
  • Fasciate Theme (1.0) [Optional] — makes it look all saucy and sweet

✋🏽 Heads up » You will need WordPress 5.5 or higher, with the Gutenberg block editor, to use the Phrase plugin.

Our Demo Site: Aznomia

Aznomia is a fictional non-profit showcasing the flora and fauna of the under-threat Amazon rainforest. Here’s what Aznomia’s website will look like when we’re done with it:

Over 40,000 plant species live in the Amazon 

I’ll assume that you know how to install WordPress for development. I personally like to use the simple, managed local dev environment Local for my WordPress dev sites.

🔗 Resource » If you want to build along with us, grab the free Fascinate WordPress theme by themebeez, and install it.

With WordPress installed, we can begin adding our content.

Adding Posts

For each species of flora or fauna, we’ll add a post that has a title, a block in its body, and a featured image.

Content and images from Wikipedia

Adding Pages

Let’s add a home page for our site. To start, we can add a page titled Home with a bit of lead text.

Pretty plain at the moment: we’ll add more to our home page soon

Setting our Home Page

By default, WordPress will use the theme’s index page, which lists recent posts, as its homepage. We can change that under Settings → Reading so that our home page is used instead.

We want to show our home page when our visitor first enters

Adding our Posts to Our Home Page

Let’s entice our visitor to explore our content once she’s hit the home page. We’ll add a few links to our flora posts, and a few more to our fauna posts.

Let’s go to Pages → All Pages → Home → Edit, and add a new columns block to our home page to house our post images and links.

We’ll select the 33/33/33 layout to add three columns side-by-side. In each column, we’ll click the +to add a block within the column, and select the image column. Under each image we can add some text linked to the respective post.

We can start typing the title of a post to get an auto-suggested link

With columns added under Flora and Fauna , our home page will now look like this:

A bit more visually interesting, no?

And that’s about it for our demo app. Let’s get to localizing it using Phrase.

Localizing our WordPress Site with Phrase

First, let’s create a new Phrase project. We’ll log in and, in our main spaces area, click the Create New Project button.

🗒 Note » If you don’t have a Phrase pro account, sign up for a free 14-day trial.

Adding the Phrase Project

This pops up the Add Project dialog

In the Add Project dialog, we can give our project a name, leave the rest of the fields in the their default state, and click the Save button.

We just need to give our project a name

Our new project will now appear in our project grid. Let’s hover over its card and click the Languages button to add the languages our site will support.


I’ll add US English and French Canadian here. You can add any languages your heart desires. Note that the first language we add becomes our source language for translations. Once we’re done, we can click Create Languages.

After that, we can click the Skip Setup button.

 We don’t need the other setup options for our project

Creating an Access Token

We’ll need an access token to connect our Phrase project to the Phrase WordPress plugin in a minute. Let’s create an access token while we’re in the Phrase console. We can do that by clicking on our name near the top-right of the screen to open a dropdown, then clicking Access Tokens.

Next, let’s click the Generate Token button.

We’ll give our token a name, leave the Scopes field as it is, and click Save. This should add a new row to the top of our access tokens list. Notice that the new token is partially revealed and there’s a Copy button next to it.

✋🏽Heads up » You won’t be able to access your token later. You need to copy it as soon as you generate it.

We’ll click the Copy button and paste our token somewhere safe.

That’s it for the Phrase setup. We can now get back to WordPress.

Installing the Phrase WordPress Plugin

We can download the Phrase plugin from its official page. Once we’ve downloaded the plugin zip file, we can open our WordPress admin and go to Plugins → Add New → Upload Plugin.

We can then click Browse, select the Phrase plugin zip file we downloaded earlier, and click Open to upload and install the plugin. Once that’s done we need to make sure to click the Activate Plugin button.

With that done, we’ll have a new Phrase menu item in our admin sidebar. Clicking that opens the API Access Token form. We can now paste the access token we generated earlier and click Save Settings.

That’s it for plugin setup. We can now get to localizing.

Localizing Pages

Let’s start localizing our home page. We can go to Pages → All Pages → Home → Edit. There we’ll find a new Phrase icon button. Once we click that button, we’ll see the Phrase plugin sidebar appear.

Under Select the project, we can open the dropdown and pick the Phrase project we created earlier. We can then select the page’s language under My post is written in and click Push content. This will upload our content for translation to our Phrase project.

Now let’s open our Phrase console and go to Projects → aznomia-wordpress → Languages. Notice that we see our source US English content is complete, and that we have untranslated French Canadian content.

Let’s click on fr-CA to open the translation editor. Our translations are listed in the left sidebar. We can select one and begin translating it in the editor. You might want to keep the SmartSuggest checkbox ticked since it can save you time by suggesting translated words as you type.

Smart Suggest is a time saver for translators

Notice that our page’s title is its own translation item. So is each block in our page’s body. We can translate each one and click Save.

🗒 Note » Keep HTML tags in the same locations in your translations as they are in the source text.

Once we’re done translating, we can go back to the WordPress admin and edit the home page again. Now we can Select All translations and click the Pull translations button to create a new, translated home page.

🗒 Note » Phrase will not sync translated WordPress slugs. Just ignore those in the translation editor.

Once the translations have been pulled, we’ll get a message reading “Pulled translations successfully.” We’ll also see a chevron next to our translation that links to the newly created translation page.

We now chose to publish the translated home page.

🗒 Note » Notice that we left our post links untranslated. That’s because at time of writing Phrase isn’t syncing these blocks. I’m working with an early version of the Phrase plugin, and the Phrase team is hard at working fixing and updating the plugin. By the time you read this, this issue may well be resolved.

Localizing Posts

Localizing posts is a lot like localizing pages, so we’ll leave that as an exercise for you.

🔗 Resource » If you want a step-by-step guide to localizing posts with the Phrase WordPress translation plugin, check out the official help documentation.

🗒 Note » At time of writing, the Phrase WordPress plugin only localized pages and posts. Support for localizing categories, tags, etc. is in the works and will be released in the future.

Once all our posts are translated and pulled in our posts listing page should look something like this.

A translated French post has been added for each English source post

Adding Polylang

We probably want to add a language switcher to our site. We can do that with the free Polylang plugin. We’ll head to Plugins → Add New and search for Polylang using the plugin search box.

It’s the one with the parrot image…sassy

With the plugin installed and activated, we’ll be invited to run its setup wizard. Let’s click the button to do so.

The Polylang add languages screen

We can pick the same languages to add to Polylang as we have in our Phrase project. We’re using US English and French Canadian in our demo site, so we’ll add those here.

The next option in the wizard regarding translating media is a matter of preference. I’ve chosen not to translate media here.

Next in line is the language to assign to content that Polylang has not assigned content to. Our source language is a good candidate here. We can manually set our translated posts and pages after we complete the wizard.

We probably want to skip the step regarding translating the home page.

We already have a translated home page that we can manually setup later. So we can click Not right now to move on.

That’s it for the polylang wizard. Let’s finish our setup manually.

Adding Our Translations to Polylang

Let’s start with our home page. We can navigate to Pages → All Pages to see the pages index. We can click the Quick Edit button next to the French home page translation that we can create with Phrase. This will open up the quick edit controls for the page.

Let’s make sure our page’s translation Status is Published and that its Language is Français. The language we’re setting here is Polylang’s.

Next, let’s open the French translation by clicking its Edit button. Then, we’ll click the gear icon near the top-right of the window to open Document settings. From there, in Polylang’s Language section, we can start typing the title of the English “Home” page. We should get an autocomplete dropdown that we can click on to set the English home page as the source of this page in Polylang.

We’ll make sure to click the Update button when we’re done. By doing that, we’ve just set our French home page as the front page in Polylang and WordPress.

Our English and French home pages are now linked in Polylang

We can link up our posts in Polylang as well. We’ll leave that as an exercise for you since it’s the exact same process as linking up our home page.

With that done, Polylang has internally linked our English content with its French counterpart. Each page or post has a localized URL as well. Our French home page, for example, is at /fr/accueil/.

🗒 Note » By default, source content (English in our case), won’t have a language code in its URL. We can change this in Polylang’s settings, however, under Languages → Settings → URL Modifications → Settings.

Adding a Language Switcher with Polylang

With all this linked content, it’s a shame that our visitors can’t manually switch between translations to read in their preferred languages. Luckily, Polylang comes with a handy language selector widget that we can stick into any of our theme’s widget areas.

Let’s head over to Appearance → Widgets, find the Language Switcher widget area settings, and set it to the Footer Middle widget area in our theme.

This will make the language switcher settings appear under the Footer Middle section near the right side of the window.

The widget settings are a matter of preference. I’ll set mine to have a title of Language and display as a dropdown. Once we Save, we can see our language switcher near the bottom of every page in our front-facing site.

More With Polylang

We can localize menus, categories, the site title and tagline, and more with Polylang. That’s a bit outside of the scope of this article, however.

📖 Go deeper » Check out our guide for localizing WordPress sites with Polylang,

Creating a WordPress Multilingual Site – Part 1: Content & Polylang. It goes into a lot more detail about working with Polylang.

With that, our Aznomia is available in both English and French.

🗒 Note » My apologies if the French translations are off. I’ve been using third-party translation tools to prepare them.

Further Reading

If you’re interested in going deeper into WordPress localization, check out our series:

The Power of Phrase Right in WordPress

Not only are we able to create, update, and sync our Phrase translations right within WordPress, we also have all the advanced features that Phrase provides us. That means our managers can set jobs for our translators from within Phrase. We can also automate translations, using machine learning to translate for us. And when we do need our translators, they can use the convenient Translation Editor in Phrase. All we have to do as WordPress devs is push up our source content and pull down the latest translations.

Check out all of Phrase’s features, and sign up for a free 14-day trial!

5 (100%) 65 votes

Best Practices for Successful Localization

Download your FREE EBOOK copy to get:

  • Insider insights from product managers
  • Tips and tricks from localization specialists
  • Concise chapter summaries for easy review
  • Our ultimate checklist to track your progress