There may be words or phrases shown in MODX prompts, tab labels, menu items, or error messages that you or your client don’t like. Changing them is dead easy. Finding them, not so much.
Users sometimes spend hours looking for Lexicon strings that are displayed in MODX. They are in some Lexicon file, but there are zillions of Lexicon files and they are not all in the same location. The fact is, that’s not where you should be looking. Even if you find the right file, changes you make there will be overwritten when you upgrade MODX or the Extra that’s producing the string.
MODX Lexicon Strings
We’ll get to where you should be looking in a bit, but first, a little background on Lexicon strings in MODX. In order to internationalize MODX, all messages and prompts in MODX, and in all properly written Extras, are stored as "Lexicon strings".
When the Login form is shown, a page with the language set to en will display the word “Password” as a prompt. If the language is set to fr, it will say: "Mot de passe" instead. Neither is contained in the Tpl Chunk used for the Login page.
Where that prompt is meant to appear, there is a language tag in the HTML code: login.password. When MODX sees this language tag, it checks the currently loaded Lexicon, or more correctly, the Lexicon cache. Hopefully the Lexicon cache matches the language of the current user. MODX looks for the login.password key, and if it finds the key, the tag in the form is replaced by the value associated with that key.
In case you’re curious, the origin of the French version of that string is this file:
core/components/login/lexicon/fr/default.inc.php, and it looks like this:
$_lang['login.password'] = 'Mot de passe';That file contains all the Lexicon strings used by the Login form for prompts and error messages.
If the key is not found, MODX replaces the language tag with the key itself: login.password. That’s why you’ll sometimes see cryptic error messages like "np_file_nf". Either someone forgot to include that key in the Lexicon file, or forgot to load the correct file into the Lexicon before the error occurred.
In a Lexicon key, by the way, the part before the first underscore is a prefix that might give you a clue to where that string is coming from. np_, for example, means that it’s coming from NewsPublisher. The nf part in any Lexicon string almost always means "not found."
Where To Look for Lexicon Strings
In the old days, if you wanted to modify a Lexicon string, you had to find the correct Lexicon file and make your changes there. The changes were all overwritten every time you upgraded. In MODX Revolution, however, the strings are still in the files, but if you change the strings properly, the new version is stored in the MODX database, where it will survive any upgrades.
When MODX loads a set of Lexicon strings into the Lexicon cache, it first gets all the strings from the file(s). Then it looks in the database for Lexicon string overrides. If you look in the modx_lexicon_entries table in the MODX database, you can see all the existing overrides. If you haven’t changed any strings yet, you may not see any.
When you go to System (gear icon) -> Lexicons in the MODX Manager, you will see all of the original and modified strings. If you look at the grid there, you’ll see three columns. The first two are Name and Value. The Name field is the Lexicon key used in language tags or in code that gets a Lexicon string. The Value field is what will be shown on the screen. The right-hand column, Last Modified On, tells when the string was last modified.
Entries that are either modified or added in Lexicon Management are shown in green. The green entries are stored in the database and will override ones that exist in Lexicon files. Unlike the ones in the Lexicon files, they will also survive upgrades.
Finding Lexicon Strings
The first thing to do is to write down the Lexicon string you’re seeing on the screen. The strings are case-sensitive, so be sure to get it exactly right. Leave off any final punctuation and any specific info like usernames, Resource and element names, or file names, that might be created dynamically. They may not be part of the Lexicon string.
Before you go looking for a language string you want to change, think a little about where the language string is coming from. If it’s something that appears in the MODX manager on a clean install, MODX itself is producing the string. If the display is created by an Extra, it is created by the Extra. Make your best guess about where the strings you want to change are coming from.
Lexicon strings are organized by Namespace, Topic, and Language. There is a search filter at the upper right of the Lexicon Management grid, but it isn’t as much help as it might be because it only searches in the currently selected Namespace, Topic and Language.
The key to finding the string you want is to go to System (gear icon) -> Lexicons and navigate to the correct Namespace, Topic, and Language. You select these using the drop-down menus at the top of the grid.
The strings used by MODX itself are all in the core namespace. If it is a basic MODX Manager string, it’s in the core namespace, but the first screen you see in Lexicon Management when you select the core namespace only shows the default topic—there are many more. Also, notice that if you scroll down, there is a page selector at the bottom of the grid. Many topics are shown on multiple pages.
The search filter will search only the current topic, but it will search on all pages of that topic. Matches will be shown at the top, followed by non-matches for strings that have been changed in that topic (shown in green).
If you’re looking for a core entry, try it in the search filter with the default topic selected. If it doesn’t show up, you can go on to the other topics. Sometimes, the topic will be obvious. At other times, it won’t. You’d expect to find the "Access Denied" message under the access topic, but it’s not there. It’s under the default topic.
One helpful trick is to leave your search filter in place as you navigate through the namespaces and topics.
Let’s work though an example. In part of the Login form’s output in English is the string, "Or, forgot your username?" Go to System (gear icon) -> Lexicons. We’ll use "forgot your username" as our search string. Put that in the search box at the upper right and press the Enter key. You’ll either see no entries, or everything will be in green. That means it didn’t find our string, which figures because the form is created by the Login Package.
Leave the search filter in place and select the login Namespace. No luck here either. That means it is not in the Login default topic. If you click on the Topic dropdown, you’ll see a forgotpassword topic—sounds promising. Click on that. Bingo. There’s our language string (unless it’s been changed by the time you read this).
Changing Lexicon Strings
As we said above, this is the easy part. Just double-click on the Value you want to change and edit it. After editing the string, be sure to click somewhere else on the page or it won’t be updated. Reload the page, and navigate again to the Login namespace and the forgotpassword topic. The line with your string should now be displayed in green, which shows that it overrides an existing Lexicon file entry and is stored in the database. Remember that your changes will survive any upgrade of MODX or any Extras.
There is one one last thing to do. You need to make sure that you changed the right Lexicon string. Sometimes the same strings are used in different namespaces and different topics. "File Not Found," for example, is used all over the place. To see if you’ve changed the correct string, clear the site cache and go to wherever the string is displayed.
You may also have to clear your browser cache to see the change. If the string hasn’t changed, you need to go back to Lexicon Management and look some more, and it might be good idea to revert the string you changed, because it is probably used somewhere else in a different context and your change might not make sense there.
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.