---
title: "wpml-config.xml Reference"
description: Configure custom post types, taxonomies, custom fields and strings in one XML file. Plugins that already ship this file work with no extra code.
url: "https://shapetranslate.com/docs/howto-config/"
updated: "2026-11-16"
category: "How-to Guides"
---

# 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

| Location | Use |
| --- | --- |
| Root of each active plugin | Shipped by the plugin author. |
| Root of the active theme and its parent theme | Shipped by the theme author. |
| `wp-content/mu-plugins/` and its sub-folders | Must-use plugins. |
| `wp-content/shapetranslate/wpml-config.xml` | Your own rules for a plugin that ships none. Read last, and safe from updates. |

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

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

| Action | Behavior |
| --- | --- |
| `copy` | Copied into a new translation, then kept in step with the original on every save (when custom field synchronization is on in Settings). |
| `copy-once` | Copied into a new translation, then left alone. |
| `translate` | Copied into a new translation as a starting point, then left alone, so later saves never overwrite an editor's work. |
| `ignore` | Never copied. Also removes a key ShapeTranslate would otherwise copy. A missing or unknown action counts as `ignore`. |

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](/docs/howto-options/).

## What is read and what is applied

| Section | Status |
| --- | --- |
| `custom-types`, `taxonomies` | Applied |
| `custom-fields` | Applied |
| `custom-fields-texts` | Read, not applied |
| `admin-texts` | Applied |
| `gutenberg-blocks` | Read, not applied |
| `custom-term-fields` | Read and exposed through `shapetranslate_wpml_config_rules`, not applied yet |

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

## Control it from code

Add a file, adjust rules, or switch the feature off

```
// 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.
