Make Custom Terms, Post Types and Taxonomies Translatable

Updated: October 17, 2024

WPML lets you set translation settings for custom terms, post types, and taxonomies you register in your code. You can do this by configuring settings in the wpml-config.xml file.

The wpml-config.xml is a configuration file that instructs WPML how it should treat elements in your themes and plugins. You can use it to define which of your custom terms, types, and taxonomies should be translated, and how.

This guide is for developers who register custom terms, post types, or taxonomies in their own custom code. If you use a third-party plugin for this, read our pages about translating custom post types and custom taxonomies.

Need to generate a wpml-config.xml file? Visit our step-by-step guide for automatically generating a configuration file using the Multilingual Tools plugin.

Registering Custom Taxonomy Terms

To translate custom taxonomy terms you need to specify the term name and the action WPML should take: translate, copy, copy-once, ignore.

Example of adding custom terms to the language configuration file

<wpml-config>
  <custom-term-fields>
    <custom-term-field action="copy">term_meta_A</custom-term-field>
    <custom-term-field action="translate">term_meta_B</custom-term-field>
    <custom-term-field action="ignore">term_meta_C</custom-term-field>
    <custom-term-field action="copy-once">term_meta_D</custom-term-field>
  </custom-term-fields>
</wpml-config>

You need to nest this markup under the wpml-config tag.

You can set the following translation options for custom fields:

translate: allows your user to translate the value of the custom term. These terms appear on the Translation Editor screen and can be translated manually or automatically or sent to other translators.
copy: copies the custom term value of the default language to the secondary languages. This means that updating the custom term value of the default language will always be copied to the secondary language. The custom terms set to copy do not show on the Translation Editor screen.
copy-once: copies the value of the custom term to the secondary language in the initial translation process. The custom terms that use the copy-once action will not appear on the Translation Editor screen. However, the user can change the custom term value of the secondary language to be different from the default language using the post editing screen.
ignore: eliminates the custom term from being copied to the secondary language.

Registering Custom Post Types

To translate custom post types you need to specify the post type name and set the translate attribute to 1. This indicates that the custom type should be translated (use 1 to translate, and 0 not to translate).

Custom types in the language configuration file

<wpml-config>
  <custom-types>
    <custom-type translate="1">book</custom-type>
    <custom-type translate="1">DVD</custom-type>
  </custom-types>
</wpml-config>

You can add the display-as-translated attribute to the tag to show the post types in the default language if no translation exists.

Using the Display as translated attribute with custom types

<wpml-config>
  <custom-types>
    <custom-type translate="1" display-as-translated="1">movie</custom-type>
  </custom-types>
</wpml-config>

You can add the automatic attribute to the tag to exclude a post type from automatic translation when using the Translate Everything Automatically mode. If you use this attribute, your entire language configuration file will only work for WPML versions 4.5.0 and up.

Using the Automatic attribute with custom types

<wpml-config>
  <custom-types>
    <custom-type translate="1" automatic="0">contact_form</custom-type>
  </custom-types>
</wpml-config>

Registering Custom Taxonomies

To translate custom taxonomies you need to specify the taxonomy name and set the translate attribute to 1.

Custom taxonomies in the language configuration file

<wpml-config>
  <taxonomies>
    <taxonomy translate="1">genre</taxonomy>
    <taxonomy translate="1">type</taxonomy>
    <taxonomy translate="0">publisher</taxonomy>
  </taxonomies>
</wpml-config>

Tip: if you have taxonomies that don’t need translation you can simply omit them from this list.

You can add the display-as-translated attribute to the tag to show the taxonomies in the default language if no translation exists.

Using the Display as translated attribute with taxonomies

<wpml-config>
  <taxonomies>
    <taxonomy translate="1" display-as-translated="1">wild-west</taxonomy>
  </taxonomies>
</wpml-config>

Additional Resources

To learn more about the wpml-config.xml file, visit the Language Configuration Files guide.

For customizing other elements using the wpml-config.xml file, visit our additional guides: