--- title: "Getting Started - Documentation - PerfLocale" description: "Step-by-step PerfLocale setup: add languages, pick a URL structure, translate your first post, drop in a switcher. End-to-end in about 15 minutes." canonical: "https://perflocale.com/docs/getting-started/" source: "https://perflocale.com/docs/getting-started/" format: "markdown" --- # Getting Started with PerfLocale From a fresh activation to a fully translated post with a working language switcher — in about 15 minutes. **Before you install.** PerfLocale needs WordPress 6.4 or newer and PHP 8.1 or newer, and works on single sites and multisite alike. Nothing else is required — no account, no API key, and no paid tier. A persistent object cache such as Redis is recommended once a site passes roughly 2,000 translation links, but is not needed to get started. Want to look before you install? [Open PerfLocale in a throwaway WordPress in your browser](https://playground.wordpress.net/?blueprint-url=https://perflocale.com/blueprint.json) — it boots a full site with the plugin already active. Nothing to set up, nothing to clean up. 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. **~15 min** total 8 steps No code required 1 ## 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** (nine of them: languages, translation groups and links, strings and their translations, translated slugs, content hashes, the background-job queue, and a migration source map). They’re prefixed with `wp_perflocale_` and stay tidy — we covered this in the [Privacy](https://perflocale.com/docs/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. - **The PerfLocale dashboard nudges you to step 2.** Until you add a language it shows a single notice — _“No active languages found. Add a language to get started.”_ — linking straight to the Languages screen. **Heads up:** if you’re migrating from WPML, Polylang, or TranslatePress, [stop here and read the migration guide first](https://perflocale.com/docs/migration/). The importer needs a clean PerfLocale install, not one with manually-added languages. 2 ## 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 (194 locales bundled). Repeat for each language you want. wp-admin / PerfLocale / Languages ### Languages \+ Add Language | Language | Code | URL slug | Status | Actions | | --- | --- | --- | --- | --- | | 🇺🇸 English | en_US | en | DEFAULT | Edit | | 🇩🇪 German | de_DE | de | Active | Edit | | 🇫🇷 French | fr_FR | fr | Active | Edit | ### 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. `de` in `example.com/de/about/`). Edit this if you want `deu` or `de-de` instead. A slug must be two or three lowercase letters, optionally followed by a hyphen and two or three more (`de`, `deu`, `de-at`) — anything else, including whole words such as `deutsch` or slugs containing digits, is refused. - **Active** — a checkbox (“Active – enable this language on the site”). Leave it off and the language gets an _Inactive_ badge on the Languages screen: you can still translate into it, but it isn’t exposed publicly yet (useful for staging a new language). The default language is always active. **Tip:** add every language you plan to support now, even if you’ll translate them later. PerfLocale charges nothing per language, and adding more later means re-checking your switcher and URL structure. Plan the full set up front. 3 ## Decide your URL structure ~2 minutes · One decision, hard to reverse Open **PerfLocale → Settings → URL & Routing**. You’ll pick one of four 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. Subdirectory Recommended example.com/de/about/ One domain, no DNS or SSL changes, full SEO authority concentrated on one host. Pick this unless you have a specific reason not to. Subdomain de.example.com/about/ Each language lives on its own subdomain. You’ll need DNS records and an SSL cert (or wildcard) for each. Useful when languages are run by separate teams. Domain per language example.de/about/ Maximum local SEO weight (Google treats `.de` as a German site). Requires WordPress multisite and one domain per language. Heavy lift. Query parameter example.com/about/?lang=de Works with every permalink structure — including Plain — and every server; the default language keeps clean URLs with no parameter. The universal fallback when your host can’t route path prefixes to WordPress. Beneath that, under **Default Language URL**, leave _Hide the language prefix for the default language_ ticked (the standard look). You can read the rest of the routing options in [URL & Routing](https://perflocale.com/docs/url-routing/) later — the defaults are sensible. **Choose carefully:** changing URL structure later requires 301 redirects from every old URL to its new equivalent, or you’ll lose Google rankings. If you’re unsure, pick subdirectory. 4 ## 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 the side column (Classic). Each language you haven’t translated yet gets a **\+ Create** button; click it and a new draft post is created, linked to the source. Once a translation exists, the button becomes **Edit**. wp-admin / Edit Post / “About Us” About Us We build performance-first WordPress plugins for teams that ship to multiple markets… ### Three ways to fill it in 1. **Type it manually.** The new draft is a normal WP post — edit title, body, blocks, anything. 2. **Auto-translate first, edit second.** In the block editor, open the draft and use _Translate from (source language)_ in its _Block translation_ panel to fill it from the source. In the classic editor, tick _Auto-Translate on Create_ in the Machine Translation settings and the draft is pre-filled the moment you click _\+ Create_ in its Translations box, for accounts allowed to use machine translation. PerfLocale routes through DeepL / Google / Microsoft / LibreTranslate (enable the Machine Translation addon on **PerfLocale → Addons**, then configure it at [Settings → Addons → Machine Translation](https://perflocale.com/docs/machine-translation/)). You then refine. 3. **Hand it off.** Give a colleague the built-in [Translator role](https://perflocale.com/docs/permissions/) so they can edit translations without full admin access, or export the post as XLIFF for an outside agency and import their file back — see [Export & Import](https://perflocale.com/docs/export-import/). Publish the translation when you’re happy. The translated post is now live at `example.com/de/about-us/` (subdirectory mode). **What about images, custom fields, SEO meta?** Standard WP fields (title, excerpt, featured image, taxonomies) are translatable per-post. Custom fields from ACF, Meta Box, etc. are auto-detected via the [Custom Fields addon](https://perflocale.com/addons/fields/). SEO plugin meta (Yoast, Rank Math, etc.) is picked up automatically — see [SEO addons](https://perflocale.com/addons/seo/). 5 ## 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: **1\. Block** Block themes (FSE) In the Site Editor, drop the _Language Switcher_ block (search “perflocale”) into your header template. Style it inline. Block: Language Switcher **2\. Classic menu** Classic themes At **Settings → Language Switcher**, tick the menu locations under _Append to classic menus_. The switcher is appended to the end of each selected menu. Settings → Language Switcher **3\. Shortcode** Anywhere 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](https://perflocale.com/docs/language-switcher/) for the full reference. example.com/about-us/ YourSite 🇺🇸 EN 🇺🇸 English 🇩🇪 Deutsch 🇫🇷 Français 6 ## 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) or `de.example.com/…` (subdomain). The translated post should load. - ✓ **Page source has ``** 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 ``** — one `` per active translation. This is how Google knows about the alternates. Search the page source for `hreflang` — you should see one entry per language. **Something off?** The most common gotcha is a caching plugin serving the original-language version under the translated URL. PerfLocale does not hook into page-cache plugins by name: each language has its own URL, so a page cache keeps one entry per language on its own — as long as it is not set to ignore the query string (which matters in query-parameter mode) or to serve one cached copy for every visitor. Purge the cache after adding a language, and see [Troubleshooting](https://perflocale.com/docs/troubleshooting/) if the wrong language persists. 7 ## 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. [ 🛒 **Selling with WooCommerce?** Translate products, categories, attributes; show prices in the visitor’s currency.](https://perflocale.com/docs/woocommerce/)[ 🤖 **Translate the whole site automatically** Wire up DeepL, Google, Microsoft, or LibreTranslate to draft 100s of posts in one click.](https://perflocale.com/docs/machine-translation/)[ 🕒 **Working with translators?** Assign the built-in Translator role so a colleague can edit translations without full admin access.](https://perflocale.com/docs/permissions/)[ 🔎 **Make Google happy** Hreflang, canonicals, sitemaps, and Yoast/Rank Math/SEOPress integration.](https://perflocale.com/docs/seo/)[ 📝 **Working with an outside agency** Export posts as XLIFF for a CAT tool, import the returned file, review before publishing.](https://perflocale.com/docs/export-import/)[ 📥 **Coming from WPML / Polylang / TranslatePress?** One-click importers that keep URLs intact and migrate translations + strings + custom fields.](https://perflocale.com/docs/migration/)[ ⚡ **Going to production** Object cache, OPcache, CDN edge caching and string-translation mode, with example query counts.](https://perflocale.com/docs/production-tuning/)[ 💬 **Translate theme & plugin strings** Anything wrapped in `__()` or `_e()` — including buttons, labels, error messages.](https://perflocale.com/docs/string-translation/) 8 ## 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](https://perflocale.com/docs/translations/) — track what’s done across the whole site. - [String translation](https://perflocale.com/docs/string-translation/) — the theme and plugin UI text around your content. - [Export & Import](https://perflocale.com/docs/export-import/) — hand work to an outside translator and take it back. ### I’m a developer - [Developer API overview](https://perflocale.com/docs/developer-api/) — the surface area at a glance. - [Hooks reference](https://perflocale.com/docs/hooks/) — 200+ actions and filters with examples. - [WP-CLI](https://perflocale.com/docs/wp-cli/) — automate translations, exports, and migrations. ### I run the infrastructure - [Production tuning](https://perflocale.com/docs/production-tuning/) — cache, CDN, database sizing. - [CDN cache tags](https://perflocale.com/docs/cache-tags/) — per-language purge. - [Edge integration](https://perflocale.com/docs/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](https://perflocale.com/docs/) — every feature has its own dedicated page. [← Back to Docs](https://perflocale.com/docs/)