# DF Translate — Complete guide

> DF Translate makes your WordPress site and WooCommerce store truly multilingual. Every translation is real content in your database (like Polylang or WPML), not a text layer rewritten on the…

- Page: <https://www.datafirefly.com/en/documentation/df-translate/>
- Language: en
- Last updated: 2026-07-07
- Other languages: [fr](https://www.datafirefly.com/documentation/df-translate/index.md), [es](https://www.datafirefly.com/es/documentation/df-translate/index.md), [de](https://www.datafirefly.com/de/documentation/df-translate/index.md), [it](https://www.datafirefly.com/it/documentation/df-translate/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-translate/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-translate/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-translate/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

DF Translate makes your WordPress site and WooCommerce store truly multilingual. Every translation is real content in your database (like Polylang or WPML), not a text layer rewritten on the fly: that's what guarantees flawless SEO and full compatibility with your theme, page builder and plugins. Machine translation is optional and runs on your own API key. This guide covers installation, language and AI-engine setup, content and string translation, multilingual SEO, the side-by-side editor, migration from Polylang, WooCommerce and troubleshooting.

## Installation

1. Download the `dftranslate.zip` archive from your DataFirefly account.
2. WordPress admin → **Plugins** → **Add New** → **Upload Plugin** → send the ZIP, then **Activate**.
3. On activation, the plugin creates its tables (translation groups, strings, string translations) and adds the **DF Translate** menu.

Compatible with WordPress 6.2 and above, PHP 8.0 to 8.3, multisite. Compatible with WooCommerce (simple products, categories, tags) and the Yoast, Rank Math, AIOSEO and SEOPress SEO plugins. No Composer dependency at deploy time.

## Five-minute quick start

1. Open **DF Translate → Settings**, **Languages** tab, and add your second language from the preset list (the free version covers 2 languages). Set the default language.
2. **Translation** tab: pick an AI engine and enter your API key (or leave it empty to translate everything by hand). Click **Test connection**.
3. Open a post or a product: in the **Language & translations** box, click **⚡ Create & translate** for the target language.
4. Review the translation in the side-by-side editor, then publish it.
5. Add the language switcher to your site (block, widget, menu or admin bar) so visitors can switch languages.

DeepL offers a free API tier: it's a good way to start at no cost. For the best writing quality on product pages, Claude (Anthropic) is recommended.

## Configuring languages

Everything happens in **DF Translate → Settings → Languages**.

### Adding a language

Use the presets dropdown (27 languages with code, locale, name and flag pre-filled) or the **Custom…** button to enter the code (e.g. `de`), locale (e.g. `de_DE`) and display name manually. The free version allows 2 languages; DF Translate Pro makes them unlimited.

### Default language, order and removal

The default language is the one your original content is in (it has no URL prefix). Reorder languages with the **▲▼** arrows (the order is reflected in the switcher) and remove one with **✕**. Removing a language from the configuration does not destroy content: it stays in the database and is re-attached if you add the language back.

You cannot remove the default language: set another language as default first. After changing languages or URL prefixes, clear your site cache and, if needed, refresh permalinks (Settings → Permalinks → Save).

## Configuring the AI translation engine

In **DF Translate → Settings → Translation**, choose the engine and enter your key.

- **Claude (Anthropic)**: best writing quality, ideal for marketing copy and product pages.
- **DeepL**: excellent value, free tier available.
- **OpenAI**: general-purpose GPT engine.
- **LibreTranslate**: self-hosted server, for full data sovereignty (you provide your instance URL).

The **Tone** field steers the style (for example "professional", "warm"). Your keys are encrypted at rest (libsodium, with an OpenSSL fallback) and are never exposed on the visitor side.

No per-word subscription and no proxy: your content only leaves your site for the provider you configure, and only when you trigger a translation. You can also configure no engine at all and translate entirely by hand.

## Translating content

Every post, page, product, category or tag has a **Language & translations** box in the editor, and a **Language** column in the lists.

### From the editor

The box shows the content's language and the status of each translation. For each missing language, **⚡ Create & translate** creates the translation and fills it with the AI engine; with no engine configured, **+ Create** creates an empty draft. AI-translated content is flagged **⚑ MT** ("needs review") until a human edits it.

### From the lists (translation matrix)

In the **Language** column, a matrix shows, for each row: its own language (solid flag), an **✎** link to each existing translation (dashed border if draft, orange if outdated), and a **⚡** or **+** button to create the missing ones. Content without a language ("orphans") offers quick assignment right in the cell.

### Filtering and bulk editing

Above the lists, view links filter by language with counts, plus a **⚑ Needs review** view. The language is also set in **Quick Edit** and **Bulk Edit** ("— No change —" option so you don't overwrite unrelated rows).

## The side-by-side editor

From a translation, the **⇆ Side-by-side** button (in the translation box, the row actions or the editor) opens a screen comparing source and target: title, slug, excerpt and SEO metadata aligned. Each field has a **⧉** button (copy from source) and a **⚡** button (AI-translate this field). A status selector, navigation between the group's languages and an outdated indicator complete the screen. Shortcut **Ctrl/Cmd + S** to save.

When you edit an already-translated source, its translations are flagged "outdated" (↻). Open them side-by-side to re-translate only the affected fields.

## Translating strings (interface text)

Text that isn't editorial content — site title, tagline, widget titles, theme labels — is managed in **DF Translate → Strings**. Enter each string's translation per language, or use **.po import/export** to hand this off to a translator or reuse an existing catalog.

## Multilingual SEO

- **hreflang**: `hreflang` tags (with `x-default`) are added automatically on every page to tell search engines about the language versions.
- **Per-language URLs**: every non-default language is prefixed (e.g. `/fr/`), for clean, indexable URLs.
- **Translated slugs**: the translation's slug is regenerated from the translated title.
- **SEO metadata**: Yoast, Rank Math, AIOSEO and SEOPress titles, descriptions and keywords are translated alongside the content.

## The language switcher

Offer language switching to visitors in the way that suits your theme:

- **Gutenberg block** "Language switcher" in the site or content editor.
- **Classic widget** in a widget area.
- **Shortcode** `[dft_switcher]` anywhere.
- **In a menu**: add a custom link with the URL `#dft_switcher`; it expands into one item per language.
- **Admin bar**: a switcher is available for logged-in users.

Flags are bundled SVGs, crisp on every system (including Windows, where emoji flags don't render).

## Translated menus

In **Settings → Menus**, assign a different menu per language to each theme location, or leave it empty to reuse the default menu. The **⚡ Generate** button clones the default menu, remapping each item to its translation (labels then follow the translated titles) and translating custom links.

## WooCommerce

DF Translate translates simple products, categories and product tags like any content. **Stock** and **price** stay synced across the languages of the same product, and the **customer's language** is saved on the order.

Variable products, order emails in the customer's language and translated URL bases are part of DF Translate Pro.

## Migrating from Polylang

If you already use Polylang, open **DF Translate → Settings** and run the one-click migration. Your languages, your content's language assignments and your translation groups are imported automatically. Your Polylang data is not modified and your existing languages are preserved (merge, not overwrite).

Back up your database before any migration, as a matter of principle. The migration is designed to be non-destructive, but a backup remains good practice.

## Dashboard and health checks

The dashboard (**DF Translate**) shows translation coverage per content type and per language, content needing review, and **health checks**: permalinks, content without a language, unconfigured engine. Several issues (like orphan content) can be fixed in one click.

## REST / headless support

The `dft_lang` and `dft_translations` fields are exposed in the REST API on translatable content types. Language filtering is done explicitly via `?lang=`; API responses are never filtered implicitly by a language cookie, which avoids corrupting the results of a headless front end.

## Uninstalling

Simply deactivating keeps all your data. If you tick the delete-data option in the settings, deleting the plugin removes DF Translate's tables and options; your WordPress content and your orders are never touched.

## FAQ and troubleshooting

**The engine connection test fails.** Check the API key, its quota on the provider side, and that your server can reach the API outbound. For LibreTranslate, check the instance URL.

**A translation stays flagged "needs review" (⚑ MT).** That's normal after a machine translation: open it and save a human edit (editor, side-by-side or import) to clear the flag.

**The language switcher doesn't appear in my menu.** Check that the custom link has exactly the URL `#dft_switcher`, then save the menu.

**Flags were showing as letters.** DF Translate uses bundled SVG flags precisely to avoid this (emoji flags don't render on Windows). Clear the cache if an old rendering persists.

**A translated page returns a 404 error.** Refresh permalinks (Settings → Permalinks → Save) after adding a language or changing URL prefixes.

**How do I go beyond 2 languages?** DF Translate Pro makes languages unlimited and adds bulk translation, autopilot, translation memory, a glossary, XLIFF export/import and WP-CLI commands.