How to Translate Theme Options and Customizer Text With WPML

You translate every page, switch the language, and the site still greets visitors with the same stubborn button labels, footer text, or Customizer tagline. It is not necessarily a WPML failure. Theme options and Customizer settings often live outside the content you translated—sometimes as interface strings, sometimes as values tucked away in the wp_options table.

That distinction is where a reliable WPML translate theme options Customizer workflow begins. A label that looks like ordinary text on the front end may need to be registered before WPML can see it; a saved setting may need a different configuration entirely. Get that first step wrong, and you can spend hours translating text that never appears where you expect.

The good news is that these “missing” translations usually have a clear path once you know what WordPress is storing and how WPML is reading it. The real challenge is spotting which kind of text you are dealing with before a single translation is added.

Understand What WPML Can Translate in Theme Options

The confusing part is that two pieces of text can sit beside each other in the Customizer yet behave completely differently. A control label such as “Footer copyright text” exists for the administrator in WordPress. The message entered into that field is what visitors see. When you need to wpml translate theme options customizer settings, it is usually the saved visitor-facing value—not the admin label—that WPML can translate.

Why Customizer text is often stored in wp_options

Most themes save Customizer and theme-panel settings in WordPress’s wp_options table. Often, one option name holds an array containing many fields: a homepage headline, footer message, phone number, social links, colors, and layout settings. WPML can translate selected values inside that stored option once they are registered for translation. It cannot reliably guess which array fields are language-dependent, so theme configuration matters.

Know which text should be translated

Translate anything a visitor reads and that should sound natural in their language: button labels, announcement bars, footer notices, homepage headings, contact descriptions, and location-specific calls to action. A footer message such as “Free delivery on orders over $50” needs its own translation.

• Usually translate: headlines, labels, promotional copy, and descriptive text.
• Usually keep shared: colors, typography choices, spacing, layout toggles, numeric IDs, and technical settings.
• Review carefully: URLs, phone numbers, prices, and addresses; these may vary by market but are not automatically language text.

Check whether the theme already supports WPML

Before creating custom configuration, check the theme developer’s WPML compatibility documentation. Then open WPML String Translation and search for the relevant option name or existing text. Developers may also include a wpml-config.xml file that tells WPML exactly which option fields to register. If that file already covers your setting, use the existing entry rather than adding duplicate rules. Admin-only control labels are different: unless the theme wraps them in WordPress translation functions, they may require a theme update or developer change to become translatable.

Register Customizer and Theme Option Values for Translation

A Customizer field can look perfectly translatable in the WordPress admin yet remain invisible to WPML. The reason is simple: many themes save those values as arrays inside wp_options, not as ordinary post content. To wpml translate theme options customizer text reliably, WPML needs to know exactly where the public-facing value is stored.

Find the option name and field key

Start with the theme documentation, then check its source code if the documentation is vague. Look for calls such as get_option(), Customizer setting definitions, or framework-specific option panels. You are trying to identify two parts: the parent option name and the array key containing the displayed text.

For example, a theme might store all settings under an option named mytheme_settings, with a homepage button label at the key hero_cta_text. You can also confirm this in the database by inspecting the relevant row in wp_options. Do not guess: a key that differs by one character will not appear in String Translation.

Add an admin-texts rule to wpml-config.xml

WPML’s custom XML configuration tells it which saved admin values should become translatable strings. Conceptually, the rule declares the option name under admin-texts, then lists the specific child key to expose. In this example, the configuration identifies mytheme_settings and its hero_cta_text field.

Place the configuration in a child theme or a small site-specific plugin rather than editing the parent theme’s wpml-config.xml. A theme update can overwrite direct changes without warning. After WPML reads the rule, visit String Translation, find the registered value, and add translations for each active language.

Choose the right translation action for each setting

• Translate: visitor-facing text that should read naturally per language, such as “Book a consultation” or a footer message.
• Copy: values that must remain identical everywhere, such as a Google Analytics measurement ID, a tracking pixel, or a shared API value.
• Copy once: a useful starting value that editors may later localize, such as a phone number format or a regional promotion URL.
• Don’t translate: internal controls, CSS classes, layout toggles, and technical settings with no reader-facing meaning.

This distinction matters. Registering every option as translatable creates clutter and invites mistakes; register the values visitors actually see.

Translate the Strings and Verify Every Language

Translate registered options in WPML String Translation

Registering a theme option is only half the job. Until you add and complete its translations, WPML has no localized value to display. In the WordPress dashboard, open WPML > String Translation and search for the option name, its domain, or a distinctive phrase from the Customizer field. Open the string, enter the translation for each active language, then mark it as complete.

This is the practical core of a wpml translate theme options customizer workflow: WPML reads the saved option and serves the matching translation when visitors switch languages. Be precise with short labels. “Read more,” “Contact,” and “Shop” can mean different things depending on where the theme uses them.

Clear caches and test the front end

A correct translation can appear missing simply because you are looking at an old cached page. Clear the WordPress object cache, any theme cache, your page-cache plugin, CDN cache, and, when necessary, the browser cache. Then visit the exact page in each language in a private browser window.

Do not test only the homepage. Check mobile menus, footer widgets, archive templates, WooCommerce screens, and any template-specific banner where the option appears. A header label may be translated while a separate mobile-header setting still uses the original text.

Fix common missing-string problems

If the string never reaches String Translation or does not change live, work through the likely causes in order:

• Confirm that the option or field key in the WPML configuration matches the key the theme actually saves.
• Save the Customizer or theme-options page at least once; unsaved defaults may not exist in the database.
• Check whether the theme stores the value outside wp_options, such as post meta, a framework settings table, or a serialized field.
• Make sure the language configuration file is in the correct theme or plugin location and has valid syntax.
• Inspect the template for hard-coded text. A string written directly in PHP is not a saved option and must be made translatable in code instead.

Keep Your WPML Translation Workflow Efficient

Document custom configuration before theme updates

Theme updates can quietly undo the assumptions behind a working translation setup. If you use custom wpml-config.xml rules to make theme options or Customizer fields translatable, keep those rules in a child theme or a small site-specific plugin rather than editing the parent theme. Record the option keys each rule covers and why they matter. After every major update, test the high-visibility strings first: homepage banners, footer copy, buttons, and contact details. A five-minute check is far cheaper than discovering that one language is showing outdated text weeks later. This is the unglamorous part of wpml translate theme options customizer work, but it prevents most maintenance surprises.

Use consistent wording across theme options and pages

Translation quality is not only about correctness; it is about repetition. “Contact us,” “Get in touch,” and “Speak to our team” may all be valid, but mixing them across navigation, Customizer labels, and landing pages makes a site feel improvised. Maintain a short approved terminology list for recurring navigation items, calls to action, checkout labels, product names, and brand terms. Give editors access to it, and revisit it when the site adds a new service or market. Consistency is especially important for WooCommerce stores, where a single term such as “Cart” appears in multiple interface and content contexts.

Optional: speed up WPML content translation with LATW AI Translator for WPML

For sites already running WPML and translating larger volumes of content, LATW AI Translator for WPML can reduce the manual workload. It is an add-on, not a replacement: WPML still provides the multilingual infrastructure, while LATW enhances its translation workflow for posts, pages, metadata, and WPML String Translation strings. You connect your own AI or machine-translation provider account, allowing translations to be sent directly from WordPress to that provider. That can be particularly useful when routine updates need to reach several languages without relying on WPML’s built-in translation credits.

Keep Theme Text Translatable for the Long Term

For WPML translate theme options Customizer workflows to remain reliable, treat each visible setting as stored data: identify the exact wp_options value, register it deliberately, translate it through WPML, and verify the result on the front end in every language. That discipline turns a frustrating “why is this still in the default language?” problem into a repeatable maintenance task.

Document the options your theme uses, keep registrations aligned with configuration changes, and test with relevant caches cleared after updates. When translation setup is maintained alongside the theme itself, localized interface text stays where it belongs—visible, consistent, and ready for every visitor.