WPML makes multilingual WordPress sites possible, but standard post types such as posts, pages, and custom post types (CPTs) often behave differently when it comes to translation. Understanding how WPML manages translations for custom post types can save you time and reduce confusion later on. This guide walks through the essential steps, common challenges, and practical tips you’ll need to get custom content translated reliably.
Understanding How WPML Treats Custom Post Types
By default, WPML enables translation for all post types that WordPress ships with—posts, pages, and attachments. A custom post type you register using register_post_type() does not automatically appear in WPML’s translation dashboard. WPML relies on two mechanisms to determine whether a CPT should be translated: the plugin’s own settings and the capabilities you assign to the post type.
When a CPT is registered, you can specify which roles have rights to edit, publish, or delete items. Those same roles also need the corresponding translation capabilities. Without adding the necessary capabilities, authors can create custom content, but WPML will not generate translation jobs for those items. The result is a site where custom posts remain in the original language only.
Activating Translation for a Custom Post Type
The first step is to open WPML’s “Settings” > “Translations” and locate the “Custom Post Types” tab. You’ll see a list of all post types currently registered on your site. Check the box next to the CPT you want to translate. After saving the settings, WPML begins to watch for new items of that type.
Even after enabling translation, you still need to grant the appropriate capabilities to user roles. This can be done in the WordPress dashboard under “Roles” > “Custom Post Type Capabilities.” Ensure the “Translation” checkbox is selected for each role that should be able to submit translations. If you’re using a translation management workflow, you’ll likely want the “Translator” role to have these rights.
Another detail that often slips through is the “Visibility” setting in the CPT’s arguments. If you set 'exclude_from_search' => true or 'public' => false, WPML may still list the post type but the front‑end search or permalinks can behave unexpectedly after translation. Keep the public flag true unless you have a specific reason to hide the post type from visitors.
Handling Custom Fields and Translation Strings
Many custom post types carry additional data beyond the default title and content. WPML provides two primary ways to translate this data: through the “String Translation” interface for individual pieces of text, and through its “Custom Fields Translation” module.
Suppose a “Book” CPT includes fields like “ISBN,” “Publisher,” and “Cover Notes.” After enabling translation, you’ll notice a “Translate” button on each field when editing a Book. Clicking that button opens the String Translation screen, where you can add a translation for that specific string. This method works well for short, isolated pieces of text that need to stay consistent across languages.
For richer content such as “Author Biography,” which is stored in a text area, WPML’s “Custom Fields Translation” will automatically create a duplicate field in the translated version. The editor sees the field side by side with the original, making it easy to adapt the text without losing context.
Be aware that some plugins add their own meta fields that WPML does not handle out of the box. If you notice a field that remains untranslated, you can add it to the “Custom Fields for Translation” list under WPML’s settings. This ensures that third‑party data also gets synced across languages.
Managing Taxonomies Linked to Custom Post Types
Taxonomies such as categories, tags, or a custom “Genre” for books are also part of the translation picture. WPML translates terms automatically once you enable translation for the associated CPT. However, there are two pitfalls to watch for.
First, if you set the taxonomy’s 'hierarchical' => true, translation may create duplicate term structures that are hard to manage. WPML handles this by creating a separate set of terms for each language, but you’ll need to map parent terms manually if you want the hierarchy to remain consistent.
Second, custom taxonomies that are not registered with WPML’s “Taxonomies” settings will not appear in the translation interface. Go to “WPML” > “Settings” > “Taxonomies” and add any custom taxonomy you intend to translate. Doing so ensures that terms appear in the language switcher and that the front‑end filters work correctly.
Editing Translations and Workflows
Once a translation job appears in the WPML dashboard, it follows the workflow you define. If you’re using the basic “Translate Everything” approach, the system creates a draft of the translated item directly in the database. Editors can then open the draft, make changes, and publish it. The original content stays untouched until the translation is approved.
For sites that use a more formal review process, the “Translation Management” component adds stages such as “In Progress,” “Review,” and “Published.” You can assign these stages to specific user roles. This setup is useful for larger teams where multiple translators and reviewers need to coordinate.
A common mistake is to forget that translation jobs can linger in the “Pending Review” status if no reviewer is assigned. Checking the “Translation Queue” regularly helps you avoid delays. If you notice a backlog, you can reassign items or publish them directly, but keep in mind that bypassing the review stage may affect quality control.
Practical Example: A Book Review Site
Imagine you run a site dedicated to book reviews. The “Book” CPT stores the title, a short summary, a rating, and a “Review Text.” You also have a custom “Author” CPT linked via a relationship field. Here’s how you’d set up translation:
- In WPML’s Custom Post Types tab, enable “Book” and “Author.”
- Ensure the “Book” CPT has its “Translation” capability assigned to the “Translator” role.
- Add “ISBN,” “Publisher,” and any other short text fields to the “String Translation” list.
- Map the “Genre” taxonomy under WPML’s Taxonomies settings so each language gets its own set of genre terms.
- Configure the “Translation Management” workflow to send new book entries to translators, then to a reviewer before publishing.
After publishing a new book in English, the system automatically creates a draft in French. The translator fills in the French fields, including the custom “ISBN” (kept identical) and the “Review Text.” The reviewer checks the final version, and once approved, visitors see the French version alongside the English one.
Common Pitfalls and How to Avoid Them
Even with WPML’s robust interface, several issues pop up repeatedly. First, not adding the CPT to WPML’s enabled list means the translation interface will never show the post type, even if the capabilities are present. Double‑check the “Custom Post Types” screen whenever you add a new CPT via a plugin or a theme.
Second, custom fields that are stored as serialized arrays can be tricky. WPML’s String Translation works with plain text, but serialized data may break if you edit it directly. If you need to translate such fields, consider storing them in separate post meta entries that WPML can recognize.
Third, translation of attachments is often overlooked. If a CPT references featured images or custom gallery fields, those media files need their own translation handling. WPML does not translate image file names automatically, but you can add alt text and captions separately for each language.
Finally, permalink structures can become misaligned after translation if the CPT’s slug differs between languages. WPML provides a “Rewrite Rules” tool that updates URLs based on the language. Running this tool after enabling translation prevents broken links.
Tips for a Smooth Translation Experience
Start with a small subset of your custom post types. Enable translation for one CPT, test the workflow, and fine‑tune the custom fields before expanding to others. This phased approach reduces the risk of overwhelming the system.
Use descriptive names for custom fields that include the language suffix, such as publisher_en and publisher_fr. This naming convention makes it easier to keep fields separate and avoid accidental overwrites.
Keep an eye on the WPML debug log. When a translation job fails silently, the log often contains the exact reason, whether it’s a missing capability or a field that isn’t translatable.
Lastly, document your CPT’s translation settings in a shared location. A simple table noting which fields are handled via String Translation, which via Custom Fields Translation, and which taxonomies are mapped can save time when new team members join.
Frequently Asked Questions
Do I need a plugin to translate custom post types with WPML?
WPML includes built‑in support for custom post types, so no extra plugin is required. You simply enable the CPT in WPML’s settings and ensure the necessary translation capabilities are assigned to user roles.
What happens if I disable translation for a CPT after creating posts?
Disabling translation will not delete existing translated posts; they remain in the database. However, WPML will stop generating new translation jobs for additional items of that type.
Can I translate custom fields that store complex data like JSON?
WPML’s String Translation works best with plain text. For JSON or other serialized data, you can break the content into individual fields that WPML can handle, or use a custom solution that parses and re‑encodes the data after translation.
Will my custom taxonomy terms appear in the language switcher?
Only if the taxonomy is listed under WPML’s Taxonomies settings. Add any custom taxonomy you want to translate there, and the terms will appear in the appropriate language filters.
How do I handle featured images for translated custom posts?
Featured images are duplicated automatically, but you’ll need to set the image alt text and caption for each language individually. WPML does not translate file names, so keep the underlying image consistent across languages.
Is there a way to bulk translate existing custom post content?
WPML offers a “Translation Management” queue where you can import existing posts and generate translation drafts in bulk. After import, you can assign translators to review each draft individually.
What should I do if a translation job never appears?
Check the CPT’s enabled status in WPML, verify that the post type’s capabilities include translation rights, and ensure the post type is not excluded from search or hidden. Refreshing the WPML cache can also resolve stale states.
