I have to admit the language files in Sugar had me confused for some time, and still do occasionally. The problem is that there are so many language files, and some of the files are auto-generated, so your not sure where a particular change you want to make is, or should be, located, or if you've forgotten a key language file when getting a package manifest ready to move to another server.
Language files are a necessary evil, if you want your application to be used internationally. Sugar is fully internationalized and has language files for over 30 different languages. Each language file in Sugar is named with a specific prefix that identifies the language. To simplify, for this article I'll just use U.S. English, the "en_us" prefix, but all my comments refer to all languages.
Language files are used to re-label fields and dropdown menus to customize your version of Sugar to your needs. If I want to call a field "Document Title," instead of "SubCategory," in my views, I would change the SubCategory field to be "Document Title" in a language file.
Let's take a peak inside some of the entries in a language file.
There are three types of entries you'll run across in a language file. (1) $mod_strings are entries used that are specific to a particular module, or area of the application. Here we see the SubCategory field being set to "Document Title" in the Documents module. All individual field labels in Sugar are prefixed with "LBL_" to let you know that this is a label. (2) $app_strings are fields used across the entire Sugar application. (3) "app_list_strings" are associative arrays that contain dropdown lists, and lists of field values used across the entire application. Language files, as you can see, are responsible for labeling everything in the Sugar application.
Now, I wish there was just one language file, but there are so many modules with specific field types that it's impractical to have just one. Sugar went the other way and has language files all over the application. Where are they located, and how do they work together?
We'll start with the mother file. When I first load Sugar, without any modifications, Sugar looks at the "include/language/en_us.lang.php" file for its initial definitions. How does it know not to get the Mexican or Canadian language file? You set your default language in "Admin->Locale" If you don't set your native language, it defaults to U.S. English.
I've talked about the multitude of language files in Sugar. Like with the initial "include/language/en_us.lang.php" for the overall application, each module in Sugar has it owns default language file in "modules/<module name>/language/en_us.lang.php". If you go to a particular, list, detail, or edit view for a particular module, Sugar loads the language file in "modules/<module name>/language/en_us.lang.php". So far so good, and depending on how many modules you have in your application, we have about 50 language files per language, all defaults. Now, the fun begins.
A typical user opens up a new Sugar installation, looks at the screen, and says, I don't want this field to say "Calls", I want it to be labeled "Leads." To try to make it easier to change labels, without being a developer, Sugar has gone to great effort to make changing labels easy in Studio, and in the Admin panel. The trouble is, you can change labels in many places in Studio, and they don't all make changes to the same file. There is one thing that is consistent though, any modifications you make to the initial default language settings are handled in a language file somewhere in the "custom" directory. This makes sense, so new versions of Sugar won't overwrite any of your field re-labeling.
I've gone through Studio, and the Admin panel, and looked at every place where you can change labels, and the corresponding file(s) that are modified when a user makes a change to a label. Here's the list.
Rename a Module, you make changes to four files depending on the module
In Studio->Labels, you saves changes to:
In Studio->Fields, you save label changes to:
In Studio->Relationships label changes go directly in the database.
In Studio->Layouts : Edit, Detail, and List Views, changes go to ->
In Studio->Layouts->Dashlets, changes to ->
In Studio dropdowns and the Dropdown editor, dropdown list changes go to ->
Some observations, just like with the default mother file in "include/language/en_us.lang.php," there is a matching default custom language file in "custom/include/language/en_us.lang.php," since this file contains all your dropdown lists, this is a very big file, mine runs over 6200 lines.
Module specific language files are in "custom/modules/<module name>/language/en_us.lang.php. This brings our total number of language files to well over 100 per language as the custom directory mimics the non-custom directories, but we're not done yet.
There are other language files used with custom drop-down lists that are module specific in: "custom/Extension/application/Ext/language/<other module filenames>"
Sugar uses the Smarty template language to create the template for some views. Smarty has its own default template language file located at "include/language/en_us.notify_template.html" and you guessed it, any changes needed are kept in "custom/include/language/en_us.notify_template.html".
And then we have "auto-generated" files. These are language files that Sugar complies from several other language files into one application file, or a module specific file, that it will then also store in cache. At the top of every "auto-generated" file, and in some instances throughout the file you'll find this warning.
If you see the file is auto-generated, just close the file. There is no use in modifying its contents, since Sugar will just over write any of your changes on the next rebuild.
The number of language files are now well over 130 per language, and that's just for one language, which brings us to our next big question. If Sugar has all these language files, how does Sugar know if I make a change in one language file, to use that change, and not some other language file, or a default language file?
That my friends, is a good question. We'll start with the obvious. Any changes you make are going into the custom directory. The custom directory always trumps the default language files, but that doesn't really answer the question, what about within the custom directory, and how do the files relate to auto-generated files?
It turns out there is a hierarchy of language files that Sugar uses when determining which language file to use for changes. I 'm going you walk you through my perception of how Sugar handles this, but I'm all ears from any Sugar gurus out there that want to comment.
Sugar will first load it's defaults
Then the module defaults, depending on what view you open, which would overwrite any of the main application defaults.
We combine this with module specific files containing the dropdown lists and field lists for a specific module. These are in separate language files depending on the customizations found in:
We'll now combine the above files, and compile them into our first auto-generated file.
And that's the file we'll use for our views, unless you've made changes, and then we get into the custom directory, which overrides any default files. Any changes in custom will override the first auto_generated default file.
First, will load the overall application customizations.
Then we override all the above files with module specific custom language files
We add module related custom dropdown lists
Now, we want to add all the previous custom files, field lists, relationship language files, and dropdowns, along with the auto-generated default file, and make our second auto-generated file. All the above files and the files in "custom/Extension/application/Ext/Language/en_us.<filenames>" are compiled into an auto-generated file located at:
This will give Sugar the combined language file with all your changes. It will put this file in cache and use it for your views.
Some after thoughts
If you've been following along with my files, you might see that the auto-generated files have an ".ext" in the file name, but don't assume they are all auto-generated. Individual modules have .ext files that are not auto-generated, such as en_us.lang.ext.php. Don't ask me why the inconsistency. That's Sugar. Not to confuse you, but there are separate "/Ext" directories, which also do not contain auto-generated files.
Here's a biggee, as stated, the language files are put in the cache directory to help speed up Sugar. If you make any custom changes that affect the language files, you should repair or rebuild the application in the Admin > Repair > Quick Rebuild & Repair to see your new labels. Always do a rebuild after changing labels.