Getting Started with PerfLocale
From a fresh activation to a fully translated post with a working language switcher — in about 15 minutes.
This guide walks you through PerfLocale end-to-end: open the admin, add a language, translate a post, ship a switcher, and verify the result. No prior multilingual experience required — if you can publish a WordPress post, you can finish this in one sitting.
After you activate the plugin
~1 minute · Just read this
You activated PerfLocale and probably noticed a new PerfLocale menu in the WordPress sidebar. Here’s what changed under the hood:
- Your existing site became the “default language”. If your site was in English, English is now the source language — nothing about your existing posts changed.
- A few database tables were added (translation links, translation memory, glossary). They’re prefixed with
wp_perflocale_and stay tidy — we covered this in the Privacy docs. - No URLs broke. Until you add a second language, your site behaves exactly as before. PerfLocale is dormant until you give it something to do.
- A “Welcome” banner appears on the dashboard pointing you here. Dismiss it once you’re finished.
Add your languages
~3 minutes
Go to PerfLocale → Languages. You’ll see one row already — your default language — with a DEFAULT badge. Click Add Language and pick from the dropdown (200+ locales bundled). Repeat for each language you want.
What each field actually does
- Language — the locale; controls date formats, plural rules, and which WordPress translation files load.
- URL slug — what appears in the URL (e.g.
deinexample.com/de/about/). Edit this if you wantdeutschorde-deinstead. Keep it short. - Status — Active means visitors can see it; Hidden means you can translate but nothing is exposed publicly yet (great for staging a new language).
Decide your URL structure
~2 minutes · One decision, hard to reverse
Open PerfLocale → Settings → URL & Routing. You’ll pick one of three layouts. This is the only setting that’s genuinely painful to change later — it determines every URL on your site, so think before you click.
Beneath that, leave “Hide default language prefix” on (the standard look). You can read the rest of the routing options in URL & Routing later — the defaults are sensible.
Translate your first post
~5 minutes
Open any post in the WordPress editor. You’ll see a new Translations panel in the right sidebar (Gutenberg) or below the editor (Classic). Click Translate to German (or whichever language) and a new draft post is created, linked to the source.
We build performance-first WordPress plugins for teams that ship to multiple markets…
Three ways to fill it in
- Type it manually. The new draft is a normal WP post — edit title, body, blocks, anything.
- Auto-translate first, edit second. Click Auto-translate in the panel. PerfLocale routes through DeepL / Google / Microsoft / LibreTranslate (configure one in Settings → Machine Translation) and pre-fills the draft. You then refine.
- Hand it off. Use the Workflow feature to assign the post to a translator with a deadline; they get notified and edit only what they’re assigned to.
Publish the translation when you’re happy. The translated post is now live at example.com/de/about-us/ (subdirectory mode).
Add a language switcher visitors can use
~2 minutes
You have a translated post, but visitors can’t reach it yet. Drop a switcher into your header, footer, or menu. Three ways, pick the one that fits your theme:
In the Site Editor, drop the PerfLocale Language Switcher block into your header template. Style it inline.
At Appearance → Menus, expand the PerfLocale Languages panel on the left and add the switcher to any menu.
Paste this into a post, page, widget, or template — works everywhere shortcodes do.
[perflocale_switcher]By default the switcher renders as a flag-and-name dropdown. Style and behaviour are configurable — see Language Switcher for the full reference.
Verify it’s working
~1 minute · Quick checklist
Open your site in a private/incognito window (so you’re not authenticated as admin) and walk this list:
- ✓The switcher appears. Visit any page on the front-end. The switcher should be where you placed it, with all active languages listed.
- ✓Clicking a language navigates correctly. Click German — the URL should change to
/de/…(subdirectory) orde.example.com/…(subdomain). The translated post should load. - ✓Page source has
<html lang="de">when viewing a German page. Right-click → View Source → first line. This signals the language to browsers, screen readers, and Google. - ✓Hreflang tags are in the
<head>— one<link rel="alternate" hreflang="de">per active translation. This is how Google knows about the alternates. Search the page source forhreflang— you should see one entry per language.
Optional next steps
Skim and bookmark what’s relevant
Once the basics work, these are the most-asked next steps. None are required — pick what you need.
__() or _e() — including buttons, labels, error messages.Where to go from here
You’re ready
If you finished the checklist in step 6, you’re running a multilingual WordPress site. The rest of the documentation is reference material — reach for it when you need a specific feature.
I’m a content person
- Translations admin page — track what’s done across the whole site.
- Workflow — assign work, set deadlines, review before publish.
- Glossary — ban auto-translation of brand terms.
I’m a developer
- Developer API overview — the surface area at a glance.
- Hooks reference — 200+ actions and filters with examples.
- WP-CLI — automate translations, exports, and migrations.
I run the infrastructure
- Production tuning — cache, CDN, database sizing.
- CDN cache tags — per-language purge.
- Edge integration — Cloudflare Workers, Vercel Edge, Netlify Edge.
Stuck on something this guide didn’t cover? Search the documentation (⌘+K) or browse the full docs index — every feature has its own dedicated page.