Internationalizing MODX Settings

Displaying setting names, descriptions, and areas, in more than one language

In the last article, we looked at creating MODX settings, but only in a single language. If your custom setting fields need to appear in more than one language in the MODX Manager, this article will show you how it's done.

MODX logo

Internationalizing the settings is a little tricky the first time you do it. It involves using several similar language keys that are easily confused. Worse yet, the instructions in the settings form are somewhat misleading.

Setting the Fields

The two fields that can be translated are the Name and Description fields. There are "rules" for how the language keys for those two fields are named, and it makes things a lot easier in the long run if you follow them.

Both fields are based on the setting's key, like this:

Name Field: 'setting_' + key
Description Field: 'setting' + key + '_desc'
Area: lowercase descriptor of the area

Here's an example using the site_start System Setting:

Key: <code>site_start</code>
Name: <code>setting_site_start</code>
Description: <code>setting_site_start_desc</code>
Area: <code>site</code>

Notice that we haven't entered the real name, description, or area here, only their lexicon keys. The name, description, and area will be in the lexicon file. The key for the area is usually a one-or-two word description of the area, with multiple words separated by an underscore, not a space. Here are some example area keys from the MODX core: core, manager, site, caching, authentication. They often stand in for longer area names. When manager is the area key, for example, "Back-end Manager" is displayed because that's the lexicon string associated with the key (sort of, we'll be more specific in the next section).

The Namespace

This step is required if you want to use more than one language with your setting(s). You could use an existing namespace on the site (e.g., core), but doing that would mean having your settings mixed up with the others and potentially having your lexicon file buried among many other lexicon files. If you create your own namespace, it will be much easier to find both your settings and your lexicon file.

Let's walk through that with a specific example using a custom namespace called "mysettings."

First, you'd create the namespace by going to System (gear icon) -> Namespaces -> Create New button. Enter the name (mysettings) and the following Core Path: {core_path}components/mysettings/. Don't put a slash after {core_path}, and don't forget the trailing slash. Save the namespace. The Core Path is necessary so that MODX can find the lexicon file when displaying any settings you create.

Now you can specify the mysettings namespace in any custom settings your create so you can find them easily in any settings tree.

In order to show how the lexicon files work, we need to create a setting in our new namespace. Let's make it a System Setting (be sure you've successfully created the mysettings namespace first). We'll use custom_theme for the key and we'll use it as an example in the following article. Go to System -> System Settings. Be sure you're on the "System Settings" tab and click on the "Create New Setting" button. Use the following values for the setting's fields:

Key:            custom_theme
Name:           setting_custom_theme
Description:    setting_custom_theme_desc
Field Type:     Textfield
Namespace:      mysettings
Area Lex entry: custom
Value:          Some Value

Save the setting and check to make sure it's in the grid. You can search for it two ways. To search for a single setting, you can put the key, or part of the key, in the search box at the upper right of the grid and press enter. To see all your custom settings, you can use the "Namespace" dropdown at the top of the settings grid (it will always show 'core' which is the default namespace). Highlight the word "core", type the beginning of your namespace name, and wait a few seconds. MODX should show your namespace just below the input box. Click on it, and the grid will load just the settings in your namespace.

The Language File

We said the actual lexicon strings are in the lexicon file, but where does it go and what's in it?

First, the name and location. The settings lexicon file must be called — (notice that in the file name it's "setting" not "settings,").

The file goes in the following directory:


For example, the English language lexicon file for the NewsPublisher settings (namespace = 'newspublisher') would be:


So, the English language file for all the settings in the mysettings namespace goes here:


Actually, the lexicon files could go in another location, as long as the Core Path variable was set to point to the directory above them. They could, for example, go in the namespace of some other component. Life is a lot simpler, though, if you put them in the conventional location described above. Then you, and others, will always know where to look for them.

To create the lexicon file, go to the Files tab in the MODX Manager. The components directory should already exist under the core directory if you've installed any extras. If not, create it by right-clicking on the core directory and selecting "Create Directory Here." Put components in the name field (you can leave the paths blank) and save the directory.

Right-click on the core/components directory and select Create Directory Here. Put mysettings in the Name field and click on the save button. Now right-click on the mysettings directory, and add a directory below it named lexicon. Then, add an en directory below the lexicon directory.

When you're finished adding the directories, you should see this structure in the tree:


Now, right-click on the en directory and select "Create File." call the file and add this to its content:

 * mysettings Setting English lexicon topic
 * @language en
 * @package modx
 * @subpackage lexicon

/* Name */
$_lang['setting_custom_theme'] = 'Custom CSS Path';

/* Description */
$_lang['setting_custom_theme_desc'] = 'Path to custom CSS file';

/* Area */
$_lang['area_custom'] = 'My Custom Settings';

Save the file

We've added comments showing the Name, Description, and Setting fields. Normally, these wouldn't be there, nor would the empty lines between the lexicon entries. The comment at the top is common and will often include the name of the author and/or a copyright notice. It's optional, though. The only required part of the file is PHP tag at the top, and the lexicon entry lines that start with $_lang

All lexicon entries in MODX take this form:

$_lang['key'] = 'Value to replace the key';

Notice that the Name and Area keys are exactly what you entered when you created the setting. The Area key, though, is a little different. We just put custom in the Area field when creating the setting. In the lexicon file, though, it gets the area_ prefix because when MODX goes to fill in the area in the Manager, that's what it looks for — area_  plus that actual entry in the form.

Coming Up

In this article, we've seen how internationalize MODX settings. In the next one, we'll look at some practical uses for custom settings.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.