Bob's Guides

LexiconHelper Snippet Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

This snippet is for use with MODX Revolution. LexiconHelper is a utility to help MODX add-on developers create and check lexicon files for their components. Note that this is not a tool for translators.

Once you have put lexicon strings in your code, LexiconHelper finds them and creates output that can be pasted into a lexicon file, so all you need to do is type in the strings you want to appear.

LexiconHelper will also check your code against an existing language file and report on missing or misspelled keys, empty strings, and strings in the language file that are not used in the code.

For more information about using lexicon strings to internationalize your component go here.

Installing LexiconHelper for MODX Revolution

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put LexiconHelper in the search box and press Enter. Click on the "Download" button, and when it changes to "Downloaded," click on the "Finish" button. That should bring you back to your Package Management grid. Right click on LexiconHelper and select "Install Package." The LexiconHelper snippet should now be installed.

Internationalization

In order to "internationalize" your add-on component, you need to replace any messages to the user with calls to the MODX lexicon method using a key to represent the string you want. MODX will look in the lexicon file for the currently specified language and replace your key with the string it finds there.

A lexicon key in the code might look like this:

<?php
if (! file_exists('myfile') ) {
    return $modx->lexicon('mc.file_not_found');
}

The corresponding line in the lexicon file, might look like this:

$_lang['mc.file_not_found'] = 'Sorry, unable to find that file';

The prefix on the language key ("mc." in the example above) is optional, but recommended. It helps keep your keys from colliding with others that might be used on the same page. The two-letter code is derived from the name of your component. To be extra safe, you could use the full name of your component as a prefix.

When the call to $modx->lexicon() is made, MODX will look through the currently loaded lexicon strings for the key you used. If it finds the key, it will replace the $modx->lexicon() call with the corresponding value.

In order for any lexicon strings to be loaded, you need to call $modx->load() before any calls to $modx->lexicon() are made. Go here for more information on loading the lexicon.

Location of Lexicon Files

Lexicon files must always be located in the core/components/mycomponent/lexicon/ directory in a subdirectory named with the two-letter language code identifying the language used in the files in that subdirectory.

Many add-on components have only one or two language files. The default.inc.php file contains any strings used by the component itself. The properties.inc.php file (if any) contains descriptions used for the component's default properties or any property sets. Here are the locations for the English and French language versions of those files

MODX root directory
    core
        components
            mycomponent
                lexicon
                    en
                        default.inc.php
                        properties.inc.php
                    fr
                        default.inc.php
                        properties.inc.php

If your Transport Package has been created properly, it will set a namespace path for your component. MODX will automatically know where to look to load the default.inc.php file when you call $modx->lexicon->load('default') in your snippet. If the namespace has not been set, you can use this form: $modx->lexicon->load('mycomponent:default'). If the current manager_language is 'en', MODX will then load the lexicon strings from this file:

core/components/mycomponent/lexicon/en/default.inc.php.

If you want to specify the language explicitly, you can use this form: $modx->lexicon->load('en:mycomponent:default').

If the 'lexicon' field of each property has been set (e.g., 'mycomponent:properties'), MODX will know where to look when a user clicks on a property description in the Manager.

Using LexiconHelper

LexiconHelper assumes that you have already put lexicon strings in your code. The lexicon() calls in the code must be in this form:

$modx->lexicon('prefix.language_string_key');

The prefix is optional, but you must use single quotes and no spaces.

In an array of properties in a Transport Package build file, each property is represented by an array of fields. This example property has an internationalized property description with language strings in the file properties.inc.php:

array(
    'name' => 'MyProperty',
    'desc' => 'mc.some_lexicon_key',
    'type' => 'integer',
    'options' => '',
    'lexicon' => 'mycomponent:properties',
    'value' => '12',
},

In the example above, the 'desc' field holds the language key and the 'lexicon' field tells MODX where the lexicon file is. When a user clicks on the property description, he or she will see the language string from the appropriate properties.inc.php file based on the current manager_language setting. The array fields can be in any order, but the order above is common.

To execute LexiconHelper, just create a new resource to display the output and put a snippet tag for it in the Resource Content field:

[[!LexiconHelper?
    &code_path=`path/to/code/directory`
    &code_file=`name of code file`
    &language_path=`path/to/language/directory`
    &language_file=`name of language file`
    &language=`en`
]]

The &language property defaults to `en` and the &language_file property defaults to default.inc.php`. These two strings will be translated if used in the path properties:

{core_path}
{assets_path}

The strings above will be replaced with the appropriate paths for your installation. They'll have a trailing slash, so be sure not to add an extra one in your property. Also, do not include the language directory name in the &language_path property. It will be added automatically.

Here is an example:

[[!LexiconHelper?
    &code_path=`{core_path}components/mycomponent/elements/snippets/`
    &code_file=`mycomponent.snippet.php`
    &language_path=`{core_path}components/mycomponent/lexicon/`
    &language_file=`default.inc.php`
    &language=`en`
    &has_properties=`0`
]]

Note that the language file must exist, though it can be empty. You can also list several files (separated by commas — no spaces) in the &code_file property if several code files share the same language file, but LexiconHelper can only check one language file at a time. If the code files are in different directories (e.g., a snippet and a plugin that share a language file), you can cheat by shortening the &code_path property and adding the end of the path to the beginning of each file in the &code_file property.

If the &has_properties property is set to `1` or if a code_file has the word 'properties' in its name, LexiconHelper will also look for internationalized property descriptions in the code.

When you preview the resource, LexiconHelper will display the information about the language strings used in the code file(s). The parsing is fairly slow, especially if the code file is large, so be patient. If there are missing strings in the language file, LexiconHelper will display them in a format that can be pasted into the language file for completion.

LexiconHelper Properties

Copyright © 2011-2025
Bob Ray