Creating Lexicon Files for other Languages

In the last article, we looked at how MODX handles lexicon strings for settings. We also created an English lexicon file for a custom System Setting. In this one, we'll see how to create more lexicon files for other languages.

File Placement

Before we start creating language files for other languages, let's consider where those files should go. In my previous article, we saw the location for the English language file. The file was called setting.inc.php because it contained lexicon strings for MODX settings (in our case, a System Setting), with the namespace mysettings. It home was under the core_path directory we specified when creating the namespace. We specified the core_path for the namespace as {core_path}components/mysettings/. The English language file is in the lexicon directory below that in a subdirectory named with the two-letter code for the language (en). So, the path to that file would be:

core/components/mysettings/lexicon/en/setting.inc.php

MODX will look for any lexicon files associated with the mysettings namespace in that lexicon/ directory. Unless you specify another language, it will look in the en directory.

So where would a French version of our lexicon file go? As you've probably guessed, it would go at:

core/components/mysettings/lexicon/fr/setting.inc.php

If you have lexicon files for English, French, Spanish, and German, the directory structure would look like this:

core
  components
    mysettings
      lexicon
        de
          setting.inc.php
        en
          setting.inc.php
        es
          setting.inc.php
        fr
          setting.inc.php

Since we're about to create a French version of our lexicon file, we need to create a directory and an empty file first. Follow the steps below:

1. Go the "Files" tab in the MODX Manager
2. Find the lexicon/ directory under the components/mysettings/ directory
3. Right-click on that lexicon directory and select "Create Directory Here"
4. Call the directory fr and click on the "Save" button
5. Right-click on the new fr directory and select "Create File"
6. Name the file setting.inc.php; leave it empty and click on the "Save" button.

You should have the English lexicon file we created in my previous article, at the file location listed earlier in this article. If it's not there, follow the steps above to create is, using en instead of fr, then paste in this code from the previous article:

<?php
/**
 * 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';

Now that we've created the French lexicon file, we need to get the translated text for it by following these steps:

1. Right-click on the English lexicon file (setting.inc.php) under the en directory and select "Edit File"
2. Copy the entire contents to the clipboard (Ctrl-a, Ctrl-c)
3. Go to the Google Translator
4. Select "Text" at the top
5. Select "English" as the source language on the left
6. Select "French" as the target language on the right.
7. Paste the content you copied from the English lexicon file (Ctrl-v) into the left-hand box
8. Copy the translated text on the right (you can't use Ctrl-a here, just highlight it all with your mouse and press Ctrl-c. Be sure you get all the text, especially the semicolon at the end.
9. Now go back and edit the empty setting.inc.php in the fr directory in the MODX file manager and paste in the code with Ctrl-v.
10. Click on the "Save" button

Notice what a nice job the Google translator has done, it has translated the comments and the $_lang[] values, but left the keys alone. It has even escaped any internal quotes in the values.

There are other translation services like Microsoft Azure and DeepL. They often provide better translations (especially DeepL), but they mangle the quotes, so the results will crash the lexicon. I'm currently working on a translation extra that will perform all the steps above for you, but it's quite tricky to avoid the problems with the quotes, so it will be quite a while before it's available. I intend to include alternative translation services like DeepL and Microsoft Azure. I had hoped to include Google Translate as an option, but so far, I haven't had any luck getting it to work. It appears that the Google documentation on their API is hopelessly out of date.

Testing

If you've followed the directions above, you should be able to change the MODX manager_language System Setting to French and see the results when you view the custom_theme System Setting you created for my previous article. The name, description, and area should appear in French.

Other Languages

As I'm sure you've figured out, the steps above should work for any language using the two-letter code for the language as the directory name. In the specific case of settings, this will only work for languages built-in to MODX. At present there are only 32 of them.

You can see the list of languages and their two-letter codes in the core/lexicon/country/en.inc/php file of your site. You can also see them presented in other languages in the other files in the country/ directory. The two-letter codes will be the same, but the language name, and sometimes the character set, will be different.

Non-setting Lexicon Strings

As I wrote just above, lexicon strings for MODX setting are limited to the built-in languages in MODX. For all other lexicon strings, you can use any language as long as you create a namespace to put the files in and a lexicon file for each language. As far as I know, you are not limited to two-letter lexicon strings as long as you use the same string for the directory name and the language specification in any language tags. There is already an example of this in the MODX lexicon files. There is a translation for Brazilian Portuguese with the code pt-br, so you could have British English, Canadian English, and Canadian French.

After a great deal of searching, I could find no definitive list of language codes for the world's languages. If there is such a list, I couldn't find it. The good news is that, as far as MODX is concerned, you can use any language code you like, as long as you create a namespace, and use the same code for the directory name that you use in your language tags. As long as you do that, MODX will find and use your lexicon entries. See this page for more information about loading lexicons and using language tags in MODX.

Coming Up

In my next article, we'll get back to looking at MODX settings and see how to use them in various locations.

---

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.