Using MODX Language Tags

Using MODX language tags to internationalize your content.

By Bob Ray  |  April 4, 2024  |  2 min read
Using MODX Language Tags

In the last article, we looked a few ways to use the MODX lexicon in a Snippet. In this one, we'll see an even simpler way that can be used if the language strings will always be displayed. This method is particularly useful for form captions.


We'll use a simple contact form as our example. This method couldn't be much easier. You just create the language file in the right place, create a namespace, and use MODX language tags where you want the lexicon strings to appear. No snippet is required because MODX will load the lexicon automatically.

As we saw in the previous article, in order for MODX to find the lexicon file, we'll need to create a namespace in System -> Namespaces. Since it's for our contact form, we'll call the namespace contactform and its core path will be:


That means our lexicon file will have to be here:


In the Namespace path, MODX will replace {core_path} with the actual path to the core, so enter it exactly as written. That way everything will still work if you move the core, or move the site to another server.

The Language File

Here's an example of our language file. We've prefixed the keys with cf_ to avoid collisions with other lexicon keys. This is important because MODX could have hundreds or even thousands of lexicon keys loaded at any given time.

$_lang['cf_name']] = 'Your Name';
$_lang['cf_subject']] = 'Subject';
$_lang['cf_email']] = 'Your Email Address';
$_lang['cf_message']] = 'Your Message';

MODX Language Tags

Language tags in MODX take this form (they can be on one line or formatted as below):

    &language=`two-letter code`

In our form, we'd place this tag where we want the word "Subject" to appear:

[[%cf_subject? &language=`en` &namespace=`contactform` &topic=`default`]]

As we saw in the last article, the value of the &language property might be replaced with a TV tag, or more likely, with a setting tag referencing the language of the current context, like this:


The example code above assumes that we've created a language_key Setting and set its value to the two-letter code of the language we want to display. The Setting could be a User, Usergroup, Context, or System Setting. MODX will look for the setting in that order and use the first one it finds (actually, the process is more complex than that, but the effect is the same). Note that at any step, if the setting exists but is empty, MODX will stop there and return the empty value.

The Form

Now all we have to do is add the language tags to our form. They will be replaced by the appropriate lexicon strings. If one of the strings is missing from the specified lexicon file, MODX will return the lexicon key itself, so it's a good practice to make the key meaningful.

Here's an abbreviated version of the form with the language tags (we've left out label tags and classes and ids for styling):

 <form action="[[~[[*id]]]]" method="post">
    [[%cf_name? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`]]:<br>
    <input type="text" name="name" value="">

     [[%cf_email? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`:<br>
    <input type="text" name="email" value="">

    [[%cf_subject? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`]]:<br>
    <input type="text" name="subject" value="">

    [%cf_message? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`]]:<br>
    <textarea rows="4" cols="50" name="message" value=""></textarea>

    <input type="submit" value="Submit">

The technique above would also work with a TV tag for the language code. If the lexicon strings are in another file instead of, we would need to modify the &topic property in the tag. For example, if the lexicon strings were in a file called, we'd add this to the tag: &topic=forms``.

Updating Lexicon Strings

Once the lexicon files exist, you can modify them at any time and clear the cache, but there is another method you can use. By going to System -> Lexicon Management, it's possible to change lexicon strings without editing a language file. This is true for the MODX core namespace and for any MODX extras you have installed. In Lexicon Management, just select the appropriate language, namespace, and topic. Then find the lexicon key you want to change and double-click on the value. Once you've changed the value, clear the site cache. That value will be used for the lexicon key from then on. Any changes you make will be stored in the database and will survive updates to MODX or to any extra.

It can be a challenge to find the lexicon key you want, but once you do, you can change any of the language strings that appear as captions in the Manager. You could change "Dashboard" to "Control Center," "Update" to "Modify," or change any of the menu items in the Manager's Top Menu. You could change "Components" to "Extras" in earlier versions of MODX, or vice versa for later versions. It's up to you.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.