Introduction

ShapeTranslate turns one WordPress site into a multilingual site. Each post, page or term gets a language, its translations are linked together, and visitors switch languages with one click.

Video tutorial

Watch the full walkthrough first, then use the pages in this guide as a reference.

What you can do

Three ideas to know first

• Default language. The language your existing content is written in. Content without a language uses it.
• Translation group. An original and its translations are linked as one group. The switcher uses this group to find the same page in another language.
• A translation is its own post. It has its own title, slug and content, so you can edit it freely.

How to read this guide

Screens in this guide carry numbered red circles 1. The list under each screen explains every number, so you can follow along in your own dashboard.

System Requirements

Check these before you install ShapeTranslate.

Server & WordPress

• WordPress6.4 or later. Tested up to 7.1.
• PHP7.4 or later. Tested up to PHP 8.4.
• PermalinksAny pretty permalink structure for directory URLs. Plain permalinks work with the query argument format.
• BrowserAny current Chrome, Firefox, Safari or Edge for the admin screens.

For subdomains or separate domains

• Every language host must point to the same WordPress installation.
• Every host needs its own SSL certificate.

Installation

Install and activate ShapeTranslate in under a minute.

Install from WordPress.org (recommended)

ShapeTranslate is free in the WordPress Plugin Directory, so you can install it without downloading anything.

1. Open Add PluginGo to Plugins → Add Plugin. Older WordPress versions call the menu Add New Plugin.
2. SearchType ShapeTranslate in the Search Plugins box and keep the filter on Keyword. The results load as you type.
3. InstallClick Install Now on the ShapeTranslate card by ShapeKode.
4. ActivateThe button turns into Activate. Click it. ShapeTranslate opens the Setup Wizard on the next page load.

Or upload the zip file

Use this when you have shapetranslate.zip, for example on a site that can't reach WordPress.org.

1. Open the uploaderGo to Plugins → Add Plugin → Upload Plugin. Older WordPress versions call the menu Add New Plugin.
2. Choose the fileSelect shapetranslate.zip as it is, without unzipping it, and click Install Now.
3. ActivateClick Activate Plugin. ShapeTranslate opens the Setup Wizard on the next page load.

Upload by FTP

1. UnzipUnzip shapetranslate.zip on your computer.
2. Upload the folderUpload the shapetranslate folder to wp-content/plugins/.
3. ActivateGo to Plugins and click Activate under ShapeTranslate.

After activation

A new ShapeTranslate menu appears in the admin sidebar with these screens:

Setup Wizard

Five short steps that make your site multilingual. Find it at ShapeTranslate → Setup Wizard.

The wizard screen

The progress strip at the top shows the five steps; the highlighted one is where you are. Continue saves the step and moves on. Back returns without losing anything.

The five steps

1. Site LanguageChoose the language your existing content is written in. It becomes the default.
2. LanguagesAdd every language you want to offer: type to search, pick one, click Add language. Remove takes one out; content already assigned to it keeps its language.
3. Language URLsChoose how URLs show the language (see URL Formats) and whether the default language shows its prefix.
4. Language SwitcherChoose the label, the layout and, optionally, a menu to add the switcher to.
5. Ready to TranslateCopy the [shapetranslate_switcher] shortcode if you need it. Click Finish Setup.

Languages Screen

Add, edit, enable, reorder and delete languages at ShapeTranslate → ShapeTranslate.

The language list

Change the default language

1. Enable the languageOnly an enabled language can be the default.
2. Click "Make default"Under the language's status. You'll see "Default language updated."

Add or Edit a Language

Click Add Language on the Languages screen, or Edit under a language.

The language form

Tips

• Always start from Choose a language. The preset fills the locale and code correctly.
• Keep URL slugs short: bn reads better than bangla.
• Add a language as disabled to prepare translations before visitors see it.

URL Formats

Decide how the language appears in your web addresses. Set it at ShapeTranslate → Settings → URL.

URL settings

Compare the formats

Translate Posts & Pages

Works the same for posts, pages and every public post type you enable under Settings → Content.

The Language box

The Language box sits in the editor sidebar. Language is the language of this post; new posts start in the default language. Under Translations, ✓ marks this post, ✎ edits an existing translation and + creates a missing one.

Create a translation by hand

1. Save the original firstThe original needs a language before it can be translated. Click Save or Publish once.
2. Click + next to the languageShapeTranslate creates a draft holding the title, content, excerpt, featured image, categories, tags and custom fields. You'll see "Translated draft created and linked."
3. Translate the textReplace the text with the translation. Change the slug for a translated URL.
4. PublishThe switcher now links both pages to each other.

Posts List & Language Filter

Every translatable list (Posts, Pages and custom post types) gets two columns and an admin-bar language filter.

The list screen

• Language column: the language of each row.
• Translations column: click + to create a translation, ✎ to edit one.
• Language filter in the admin bar: shows only content in one language, or "Show all languages". New posts start in the chosen language.

What the icons mean

Translations Dashboard

One table at ShapeTranslate → Translations that shows what is translated and what is missing across the site.

The dashboard

• One column per language. Read across a row to see that item in every language.
• Cells. ✓ done, ✎ draft, + click to create the translation.
• Filters. Content type, language and status: missing, completed or draft translations.
• Search. Find content by title.

Good ways to use it

• Filter by Missing translations and one language to get a to-do list.
• Filter by Draft translations to find work that is not published yet.

Categories & Tags

Translate categories, tags and any taxonomy you enable under Settings → Content.

Translate a term

1. Open Posts → CategoriesEach term has a Language field, and the list has Language and Translations columns.
2. Edit a term and click +ShapeTranslate creates a linked term named like News (Français) with the slug news-fr.
3. Rename itSet the translated name and slug, then click Update.

When you translate a post, its categories and tags switch to their translations automatically.

Media

Give images a different title, alt text, caption and description in each language.

Turn it on

1. Open Settings → ContentTick Translate media titles, alternative text, captions, and descriptions.
2. Edit an imageThe attachment details now have a Language field, and the Media Library gets Language and Translations columns.
3. Create the translationClick + next to a language. ShapeTranslate creates that language's media record. Type the translated title, alternative text, caption and description, then click Update.

Menus

Give each language its own menu at Appearance → Menus. For block themes, see Site Editor.

The Menus screen

Assign menus to languages

• Use the per-language theme locations on the Menus screen, or
• Go to Settings → Switcher → Navigation Menus and Theme Locations.
• One menu can belong to one language only.

String Translation

For text that isn't a post: site title, tagline, date and time formats, widget text and strings registered by themes and plugins. Find it at ShapeTranslate → String Translation.

The string editor

String groups

WordPress holds the site title, tagline, date format and time format. Widgets holds widget titles and text. Strings registered with shapetranslate_register_string(), and plugins that ship a wpml-config.xml file, add their own groups.

Switcher Placements

The switcher sends a visitor to the same page in another language. A floating switcher is on from day one, so every language is reachable right after setup.

Where you can place it

What it looks like

On the demo site, the switcher sits in the header menu, and the floating switcher is on.

Add it to a classic menu

Add the block

Add it with Elementor

Switcher Settings

Site-wide defaults for every switcher, at ShapeTranslate → Settings → Switcher.

The Switcher tab

Override per placement

A single block, menu item or shortcode can use its own settings. The values on this tab are only the defaults.

Site Editor (Block Themes)

Translate templates, template parts and navigation menus in block themes.

Translate a header or footer

1. Open the partAppearance → Editor, then open a template, template part or navigation menu.
2. Open the Languages panelFrom the editor's top toolbar.
3. Create or adopt a version+ creates a version in another language. Use an existing one adopts a part you already have.

A language without its own version uses the default language's version automatically.

Page Builders

Headers, footers, popups and templates are translated per language, and their display rules follow the language.

Supported plugins

Yoast SEO, Rank Math and SEOPress keep their own title and meta description per translation, and ShapeTranslate adds the language links next to them.

Settings Overview

ShapeTranslate → Settings has seven tabs. Each tab saves on its own with Save Changes.

The tabs

Screenshots of the URL, Content and Switcher tabs are on URL Formats, Media and Switcher Settings.

General

Synchronization

SEO

Advanced

Synchronization items

Import & Export

Move your ShapeTranslate settings to another site from Settings → Advanced.

Copy settings to a new site

1. ExportClick Download Settings JSON. The file is named like shapetranslate-settings-2026-10-11.json.
2. Install ShapeTranslate on the new siteAdd the same languages first. The import stops if a language in the file is not on the new site yet.
3. ImportChoose the file, or paste the JSON, and click Import Settings.

Uninstall behavior

Deactivating never deletes data. Data is removed only when you tick Delete all ShapeTranslate data when the plugin is uninstalled and then delete the plugin.

Developer Quick Start

Everything public is a global function prefixed shapetranslate_ or a hook named shapetranslate_*.

Ground rules

• Use the API after shapetranslate_loaded (or on init).
• All functions are safe when ShapeTranslate is inactive: they return an empty value or a WP_Error.
• A language reference can be a URL slug (bn), code, locale (bn_BD), language ID or record. Empty means the current language.
• shapetranslate_translate_string() returns unescaped text. Escape it, or use shapetranslate_esc_html__().

Examples

add_action( 'shapetranslate_loaded', function () {
    $slug  = shapetranslate_current_language();  // 'bn', 'en', …
    $bn_id = shapetranslate_get_post( 42, 'bn' ); // 0 when none
    $home  = shapetranslate_home_url( 'fr' );
} );

add_action( 'init', function () {
    shapetranslate_register_string( 'my-theme', 'footer_note', 'Made with care in Dhaka' );
} );

// In the template:
shapetranslate_esc_html_e( 'my-theme', 'footer_note', 'Made with care in Dhaka' );

<?php
shapetranslate_language_switcher( array(
    'display'              => 'native_name', // name | language_code
    'layout'               => 'dropdown',    // horizontal | vertical
    'show_flags'           => true,
    'unavailable_behavior' => 'home',        // hide | disabled | current
) );
?>

PHP Functions

From includes/api.php and includes/functions.php.

Languages

Posts and terms

Strings and switcher

Shortcode & Blocks

Attributes for [shapetranslate_switcher] and the two switcher blocks.

Shortcode

[shapetranslate_switcher layout="dropdown" show_flags="true" hide_current="true"]

Defaults shown are the plugin's own. The values saved under Settings → Switcher replace them site-wide.

Blocks

• shapetranslate/language-switcher: attributes display, layout, hideCurrent, hideMissing, unavailableBehavior, showFlags, showDisabled, ariaLabel.
• shapetranslate/navigation-language-switcher: only inside core/navigation; adds dropdown (show as submenu).

Front-end CSS and JS handles: shapetranslate-switcher, shapetranslate-floating-switcher. The switcher markup has the class shapetranslate-switcher.

Hooks Reference

Every action and filter ShapeTranslate fires. filter changes a value; action runs your code at that moment.

Common recipes

add_filter( 'shapetranslate_supported_post_types', function ( $post_types ) {
    $post_types[] = 'portfolio';
    return array_unique( $post_types );
} );

add_filter( 'shapetranslate_copy_post_meta_keys', function ( $keys, $sync ) {
    $keys[] = '_my_price_note';
    return $keys;
}, 10, 2 );

add_action( 'shapetranslate_translation_created', function ( $new_post_id, $source_id, $language ) {
    update_post_meta( $new_post_id, '_needs_proofreading', 1 );
    // $language is the language record: $language['url_slug'], $language['locale'] …
}, 10, 3 );

add_filter( 'shapetranslate_language_cookie_lifetime', function () {
    return 30 * DAY_IN_SECONDS;
} );

add_filter( 'shapetranslate_should_detect_language', function ( $allowed ) {
    $ua = isset( $_SERVER['HTTP_USER_AGENT'] ) ? (string) $_SERVER['HTTP_USER_AGENT'] : '';
    return $allowed && ! preg_match( '/bot|crawl|spider/i', $ua );
} );

All hooks

Translate Plugin Options

Make text saved in a WordPress option translatable, so get_option() returns the right language on the front end.

How it works

You declare an option, and the keys inside it that hold text. Every text value found there becomes a registered string. Translate it on the Strings screen, in the group named after the plugin or theme. The code that reads the option needs no change.

Declare with wpml-config.xml

Say a plugin saves its settings in the option my_plugin_settings:

my_plugin_settings = array(
    'button_text' => 'Book now',
    'api_key'     => 'abc123',
    'messages'    => array( 'success' => 'Thank you!', 'error' => 'Try again.' ),
);

<wpml-config>
  <admin-texts>
    <key name="my_plugin_settings">
      <key name="button_text" />
      <key name="messages">
        <key name="success" />
        <key name="error" />
      </key>
    </key>
  </admin-texts>
</wpml-config>

api_key is not listed, so it is never registered or translated.

A single-value option

When the option itself is the text, declare its name with no children:

<admin-texts>
  <key name="my_plugin_footer_note" />
</admin-texts>

Wildcards

A * in an option name is matched against the options the site actually has. Use it for options that repeat per item:

<admin-texts>
  <key name="widget_my_plugin_*">
    <key name="title" />
  </key>
</admin-texts>

Translate the strings

1. Load a page that reads the optionOpen any front-end page that uses it. The strings register the first time the option is read.
2. Open the Strings screenFind the group named after your plugin or theme (for example plugins/my-plugin).
3. TranslateType the translations. Visit the site in that language to check.

Alternative: register one string in PHP

For a single value in your own code, skip the XML:

add_action( 'init', function () {
    shapetranslate_register_string( 'my-plugin', 'button_text', get_option( 'my_plugin_button' ) );
} );

// Where you print it:
shapetranslate_esc_html_e( 'my-plugin', 'button_text', get_option( 'my_plugin_button' ) );

Options whose names start with shapetranslate are never translated.

wpml-config.xml Reference

Configure custom post types, taxonomies, custom fields and strings in one XML file. Plugins that already ship this file work with no extra code.

Where ShapeTranslate looks

The file name is always wpml-config.xml. Changes are picked up automatically when a plugin or theme is activated, deactivated, switched or updated, and when the file's modified time changes.

A complete example

<wpml-config>
  <custom-types>
    <custom-type translate="1">portfolio</custom-type>
    <custom-type translate="0">internal_log</custom-type>
  </custom-types>

  <taxonomies>
    <taxonomy translate="1">project_type</taxonomy>
  </taxonomies>

  <custom-fields>
    <custom-field action="translate">subtitle</custom-field>
    <custom-field action="copy">price</custom-field>
    <custom-field action="copy-once">gallery</custom-field>
    <custom-field action="ignore">_edit_lock</custom-field>
  </custom-fields>

  <admin-texts>
    <key name="my_plugin_settings">
      <key name="button_text" />
    </key>
  </admin-texts>

</wpml-config>

Post types and taxonomies

• translate="1" makes the type or taxonomy available to translate. It includes non-public types such as page builder headers and templates. It does not tick the box in Settings: the site owner still decides what is translated.
• translate="0" removes it completely. It cannot be turned on from Settings.

Custom fields

Declare what happens to a post meta key when a translation is created or synchronized.

A declaration can never switch synchronization on. If a site turned custom field synchronization off, copy only seeds new translations, while ignore always applies.

Strings

<admin-texts> is covered in Translate Plugin Options.

What is read and what is applied

Keys that use a lookup type or a search method other than wildcards are skipped, never guessed.

Control it from code

// Read an extra file.
add_filter( 'shapetranslate_wpml_config_files', function ( $files ) {
    $files['my-addon'] = WP_CONTENT_DIR . '/my-addon/wpml-config.xml';
    return $files;
} );

// Adjust the parsed rules.
add_filter( 'shapetranslate_wpml_config_rules', function ( $rules ) {
    unset( $rules['post_meta']['price'] );
    return $rules;
} );

// Turn it off in wp-config.php:
define( 'SHAPETRANSLATE_WPML_CONFIG', false );

The key of each file (for example plugins/my-plugin) becomes the string group name.

Translate Emails from Any Plugin

Send an email in the recipient's language, with WordPress's own locale switching. ShapeTranslate follows it.

How it works

1. Find the recipient's localeFor a user, call get_user_locale( $user_id ). It returns the locale saved in the profile.
2. Switch to itCall switch_to_locale( $locale ). WordPress unloads the old translations and loads the new ones.
3. Write and send the emailUse normal translation functions. ShapeTranslate strings and translated options answer in the same language.
4. RestoreCall restore_previous_locale() so the rest of the request is unchanged.

$locale = get_user_locale( $user_id );
switch_to_locale( $locale );

wp_mail(
    $to,
    __( 'Welcome', 'my-plugin' ),
    shapetranslate_translate_string( 'my-plugin', 'welcome_body', 'Thanks for joining.' )
);

restore_previous_locale();

What follows the switch

If no enabled language uses the switched locale, ShapeTranslate leaves its answer as it was.

WordPress emails

WordPress sends the welcome and password-reset emails in the user's locale. ShapeTranslate saves it for you: a visitor who registers on a translated page gets that page's locale saved in the profile.

• Accounts created in wp-admin are left alone, because they say nothing about the new user's language.
• Users who can edit posts are left alone, because the locale is also the language of their dashboard.
• A locale that is already saved is never replaced.
• Users who registered before ShapeTranslate was installed have no locale. Set it in their profile.

Plugins that load their own translations

Most plugins need nothing. A plugin that loads its text domain by hand should load it again on each switch:

add_action( 'change_locale', function ( $locale ) {
    load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
} );

Check that it works

1. Register from a translated pageOpen a page with a language prefix, such as /bn/, and create an account.
2. Check the profileThe user's locale is the one of that language.
3. Trigger the emailUse the password reset. The email should arrive in that language, even if you started it from another one.

Hooks

REST API & Constants

Routes under shapetranslate/v1 and wp-config.php constants.

REST API (shapetranslate/v1)

Core REST collections accept lang and lang_fallback.

Constants

There are no WP-CLI commands in version 1.0.1.

Data Storage

Where ShapeTranslate keeps languages, translations and settings.

FAQ & Troubleshooting

Quick answers to the questions we hear most.

Common questions