Language Strings

Language strings provide an element of internationalisation to SuiteCRM. It allows specifying different strings to be used in different languages making it much easier to provide translations for modules and customisations. Even if you are only targeting a single language it is still worth using the language string functionality in SuiteCRM because it allows the simple changing of strings within SuiteCRM and it also allows users to customise the labels used in your customisations. There are three main types of language strings that we will cover here.

At the core, the language strings are a key value store. The keys are used throughout SuiteCRM and the values are loaded based on the current language.

Languages are handled in SuiteCRM by prefixing the file name with the IETF language code for the language that this file contains. Here are some examples of different language file names:

  • Core Accounts language file for en_us (United States English) - modules/Accounts/language/en_us.lang.php

  • Core Cases language file for es_es (Spanish as spoken in Spain) - modules/Cases/language/es_es.lang.php

  • Custom language file for de_de (German) - custom/Extension/application/Ext/Language/de_de.SomeCustomPackage.php

SuiteCRM will choose the language prefix to be used based on the language the user selected when logging in or the default language if none was selected. Generally when a language file is loaded the default language files and the en_us files will also be loaded. These files are then merged. This ensures that there will still be a definition if there are language keys in either en_us or the default language that don’t have definitions in the current language. In essence the language “falls back” to the default language and en_us if there are missing keys.

Module Strings

Use

Module strings are strings associated with a particular module. These are usually, for example, field labels and panel name labels, but they may be used for anything that is specific to a single module.

Definition location

Module strings are defined in the $mod_strings array. This is initially defined in modules/<TheModule>/language/<LanguageTag>.lang.php, for example
modules/Accounts/language/en_us.lang.php.

Customisation location

Customisations can be made to the module strings by adding a new file in
custom/Extension/modules/<TheModule>/Ext/Language/<LanguageTag>.<Name>.php

(<Name> in this case should be used to give it a descriptive name). An example is
custom/Extension/modules/Accounts/Ext/Language/en_us.MyLanguageFile.php.

See the extensions section for more information on the Extensions folder.

Application Strings

Use

Application strings are used for language strings and labels that are not specific to a single module. Examples of these may include labels that will appear in the headers or footers, labels that appear on search buttons throughout SuiteCRM or labels for pagination controls.

Definition location

The application strings are defined in the $app_strings array. This is initially defined in
include/language/<LanguageTag>.lang.php.

Customisation location

Customisations can be made to the application strings in two ways. Firstly you can edit the file
custom/include/language/<LanguageTag>.lang.php.

However to promote modularity it is recommended that you add a new file in the location
custom/Extension/application/Ext/Language/<LanguageTag>.<Name>.php.

For example custom/Extension/application/Ext/Language/es_es.MyAppLanguageFile.php. <Name> should be used to give the file a descriptive name.

An example of a redefinition in this directory would look like this:

<?php
$app_strings['LBL_HELLO'] = 'Hello';

See the extensions section for more information on the Extensions folder.

Application List Strings

Use

Application list strings are used to store the various dropdowns and lists used in SuiteCRM. Most of these are used as options for the various enum fields in SuiteCRM e.g the account type or the opportunity sales stage.

Definition location

The application list strings are defined in the $app_list_strings array. Similar to the $app_strings array this is initially defined in include/language/en_us.lang.php.

Customisation location

Customisations can be made to the application list strings in two ways. Firstly you can edit the file
custom/include/language/<LanguageTag>.lang.php.

However to promote modularity it is recommended that you add a new file in the location
custom/Extension/application/Ext/Language/<LanguageTag>.<Name>.php

(<Name> should be used to give the file a descriptive name). For example
custom/Extension/application/Ext/Language/es_es.MyAppListLanguageFile.php.

See the extensions section for more information on the Extensions folder.

Why and when to customise

Generally language strings should be changed from within SuiteCRM using the studio tool. However there are times when it can be simpler to add or modify language strings as described in the previous section. If you are importing a large number of language strings or dropdown options it can be simpler to create a new file to add these values. Similarly if you are adding entirely new functionality, it is usually best to simply add these language strings as new values.

Usage

Language strings are used automatically throughout SuiteCRM. For example in metadata you can specify the language strings to display for fields. However in some cases you will want to access and use the language strings in custom code. There are several ways to do this.

Globals

The $mod_strings, $app_strings and $app_list_strings variables are all global and can be accessed as such. $app_strings and $app_list_strings will always be available. However $mod_strings will only contain the strings for the current module (see the next section for other ways of accessing $mod_strings).

Example 9.1: Accessing language strings globally
function someFunction(){
    global $mod_strings, $app_strings, $app_list_strings;
    /*
     * Grab the label LBL_NAME for the current module
     * In most modules this will be the label for the
     * name field of the module.
     */
    $modLabel = $mod_strings['LBL_NAME'];

    $appLabel = $app_strings['LBL_GENERATE_LETTER'];

    /*
     * Unlike the previous two examples $appListLabel will be an
     * array of the dropdowns keys to it's display labels.
     */
    $appListLabel = $app_list_strings['aos_quotes_type_dom'];

    //Here we just log out the strings
    $GLOBALS['log']->debug("The module label is $modLabel");
    $GLOBALS['log']->debug("The app label is $appLabel");
    $GLOBALS['log']->debug("The app list label is ".print_r($appListLabel,1));
}

Translate

As an alternative to using globals or, if you are in a different module than the language string you wish to retrieve you can use the translate method.

Example 9.2: translate method signature
translate(
        $string,
        $mod='',
        $selectedValue='')
$string

The language string to be translated.

$mod

The module this string should come from. Defaults to the current module if empty.

$selectedValue

For dropdown strings. This will return the label for the key $selectedValue

Here is an example of the above in action. Note that we do not have to worry about whether the label is a Module string, an Application string or an Application list string, as all of these will be checked (in that order - the first matching value will be returned).

Example 9.3: Example translate method calls
function someFunction(){
   //Grab the label LBL_NAME for the current module
   $modLabel = translate('LBL_NAME');

   //Grab the label LBL_NAME for the AOS_Products module
   $productModLabel = translate('LBL_NAME','AOS_Products');

   $appLabel = translate('LBL_GENERATE_LETTER');

   /*
    * Return the label for the `Other` option of the `aos_quotes_type_dom`
    * We don't care about the module so this is left blank.
    */
   $appListLabel = translate('aos_quotes_type_dom','','Other');

   //Here we just log out the strings
   $GLOBALS['log']->debug("The module label is $modLabel");
   $GLOBALS['log']->debug("The module label for Products is $productModLabel");
   $GLOBALS['log']->debug("The app label is $appLabel");
   $GLOBALS['log']->debug("The app list label is ".print_r($appListLabel,1));
}

JavaScript

Finally, you may be using JavaScript (for example in a view), and wish to display a language string. For this you can use the SUGAR.language.get method, which is similar to the translate method in example 9.3.

Example 9.4: SUGAR.language.get method signature
SUGAR.language.get(
              module,
              str
);
module

The module a language string will be returned for. You should supply app_strings or app_list_strings if the label you wish to retrieve is not a module string.

str

The key you want to retrieve a label for.

Example 9.5: Example SUGAR.language.get method calls
function someFunction(){

   /*
    * Grab the label LBL_NAME for AOS_Products
    * Note that, unlike the translate function in example 9.3
    * the module name is required.
    */

   var modLabel = SUGAR.language.get('AOS_Products', 'LBL_NAME');

   /*
    * As mentioned above we explicitly need to pass if we are retrieving
    * an app_string or app_list_string
    */
   var appLabel = SUGAR.language.get('app_strings', 'LBL_GENERATE_LETTER');
   var appListLabel = SUGAR.language.get('app_list_strings',
                                         'aos_quotes_type_dom');

   //Here we just log out the strings
   console.log("The module label is "+modLabel);
   console.log("The app label is "+appLabel);
   console.log("The app list label is "+appListLabel);
}

↩

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.