Localizing with the Phrase WordPress Translation Plugin

Software localization

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 […]
Software localization blog category featured image | Phrase

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 Phrase
  • 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:

Our finished demo app | Phrase

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.

Adding a WordPress post | Phrase

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.

Adding a homepage to WordPress | Phrase

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.

Setting our homepage in WordPress | Phrase

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.

Adding our posts to our homepage in WordPress | Phrase

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.

Writing a title for our post in WordPress | Phrase

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:

Our set up homepage | Phrase

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 subscription, sign up for a free 14-day trial.

Adding the Phrase Project

Creating a new project in Phrase | Phrase

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.

Add project dialog | Phrase

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.

Adding a new language to our project | Phrase

 

Set up languages dialog menu | Phrase

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.

Skipping the project setup in Phrase | Phrase

 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.

Dropdown menu access token menu point in Phrase | Phrase

Next, let’s click the Generate Token button.

Generate a Token button in Phrase | Phrase

Generate a token dialog menu in Phrase | Phrase

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.

Copying the user based access token for our translation project | Phrase

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.

Adding the Phrase plugin to WordPress | Phrase

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.

Entering our API access token into the Phrase plugin in WordPress | Phrase

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.

The Phrase plugin sidebar | Phrase

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.

Checking our translation status in Phrase | Phrase

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 Autocomplete checkbox ticked since it can save you time by suggesting translated words as you type.

Translating our WordPress content with Smart Suggest in Phrase | Phrase

Autocomplete 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.

Pull translations button to create a new, translated home page | Phrase

🗒 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.

Our newly created translation page | Phrase

We now chose to publish the translated home page.

Our translation page published | Phrase

🗒 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.

Our post listing | Phrase

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.

Installing Polylang | Phrase

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.

Polylang setup wizard | Phrase

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.

Skipping the homepage translation step in the Polylang translation setup | Phrase

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.

Quick edit controls for our French translation | Phrase

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.

Setting the English home page as the source of this page in Polylang | Phrase

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 | Phrase

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.

Adding a Language Switcher with Polylang | Phrase

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

Language switcher settings in the Footer Middle section | Phrase

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.

Language switcher drop down at the end of our homepage | Phrase

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.

Finished WordPress demo site | Phrase

Finished WordPress demo site translated into French | Phrase

🗒 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!