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.
Simplicity
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:
{core_path}components/contactform/
That means our lexicon file will have to be here:
core/components/contactform/lexicon/en/default.inc.php
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 default.inc.php
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.
<?php
$_lang['cf_name']] = 'Your Name';
$_lang['cf_subject']] = 'Subject';
$_lang['cf_email']] = 'Your Email Address';
$_lang['cf_message']] = 'Your Message';
When MODX looks for a language file, if no topic is specified, MODX assumes you want the default language file, which is always called default.inc.php
. For many extras, there is only one lexicon file for each language. It's always called default.inc.php
, and it can be found in the directory named with the two-letter language code (en, de, fr, es, ru, etc.) in this directory: core/components/componentname/lexicon/
.
MODX Language Tags
Language tags in MODX take this form (they can be on one line or formatted as below):
[[%lexicon_key?
&language=`two-letter code`
&namespace=`namespaceName`
&topic=`topicName`
]]
In our form, we'd place this tag where we want the word "Subject" to appear:
[[%cf_subject? &language=`en` &namespace=`contactform` &topic=`default`]]
If your lexicon file is default.inc.php
, you can leave out the &topic
property, but having it there is a good reminder for you or others who might look for the file.
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:
&language=`[[++language_key]]`
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="">
<br>
[[%cf_email? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`:<br>
<input type="text" name="email" value="">
<br>
[[%cf_subject? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`]]:<br>
<input type="text" name="subject" value="">
<br>
[%cf_message? &language=`[[++language_key]]` &namespace=`contactform` &topic=`default`]]:<br>
<textarea rows="4" cols="50" name="message" value=""></textarea>
<br><br>
<input type="submit" value="Submit">
</form>
The technique above would also work with a TV tag for the language code. If the lexicon strings are in another file instead of default.inc.php
, we would need to modify the &topic
property in the tag. For example, if the lexicon strings were in a file called forms.inc.php
, we'd add this to the tag: &topic=
forms``.
It's common to leave out the &language
property in language tags. If it's not sent, the MODX lexicon will use the cultureKey
System Setting (or other setting) in its place. Multi-language sites often have a different language for each context and specify the language in a contextKey
Context Setting. You could also make it a User Group Setting if you want to have different User Groups see different languages. You could even make it a User Setting, if some individual users have different preferred languages.
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.