Application Labels and Lists

Overview

Sugar, which is fully internationalized and localizable, differentiates languages with unique language keys. These keys prefix the files that correspond with particular languages. For example, the default language for the application is English (US), which is represented by the language key en_us. Any file that contains data specific to the English (US) language begins with the characters en_us. Language label keys that are not recognized will default to the English (US) version.

For more information on language keys, please refer to the Languages page.

Application Labels and Lists

$app_list_strings and $app_strings

The $app_list_strings array contains the various dropdown lists for the system while $app_strings contains the system application labels. The initial set of definitions can be found in ./include/language/<language key>.lang.php. As you work within the system and deploy modules and lists through Studio, any changes to these lists will be reflected in the language's extension directory: ./custom/Extension/application/Ext/Language/<language key>.<list name>.php.

Customizing Application Labels and Lists

If you are developing a customization and want to be able to create or edit existing label or list values, you will need to work within the extension application directory. To do this, create ./custom/Extension/application/Ext/Language/<language key>.<unique name>.php.

The file should contain your override values with each label index set individually. An example of this is:

  <?php

$app_strings['LBL_KEY'] = 'My Display Label';
$app_list_strings['LIST_NAME']['Key_Value'] = 'My Display Value';

Once the file is created with your adjustments, navigate to Admin > Repair > Quick Rebuild & Repair. This will compile all of the Extension files from ./custom/Extension/application/Ext/Language/ to ./custom/application/Ext/Language/<language key>.lang.ext.php.

Hierarchy Diagram

Retrieving Labels

There are two ways to retrieve a label. The first is to use the translate() function found in ./include/utils.php. This function will retrieve the label for the current user's language and can also be used to retrieve labels from $mod_strings, $app_strings, or app_list_strings.

An example of this is:

  require_once 'include/utils.php';
$label = translate('LBL_KEY');

Alternatively, you can also use the global variable $app_strings as follows:

  global $app_strings;

$label = '';
if (isset($app_strings['LBL_KEY']))
{
    $label = $app_strings['LBL_KEY'];
}

Note: If a label key is not found for the user's preferred language, the system will default to "en_us" and pull the English (US) version of the label for display. 

Retrieving Lists

There are two ways to retrieve a label. The first is to use the translate() function found in include/utils.php. This function will retrieve the label for the current user's language.

An example of this is:

  require_once 'include/utils.php';
$list = translate('LIST_NAME');

//You can also retrieve a specific list value this way
$displayValue = translate('LIST_NAME', '', 'Key_Value');

Alternatively, you can also use the global variable $app_list_strings as follows:

  global $app_list_strings;

$list = array();
if (isset($app_list_strings['LIST_NAME']))
{
    $list = $app_list_strings['LIST_NAME'];
}

Note: If a list key is not found for the user's preferred language, the system will default to "en_us" and pull the English (US) version of the list for display.

Accessing Application Strings in Sidecar

All language-pack strings are accessible within the Sidecar framework.

$app_strings

To access $app_strings in Sidecar, use app.lang.getAppString:

  app.lang.getAppString('LBL_MODULE');

To access $app_strings in your browser's console, use SUGAR.App.lang.getAppString:

  SUGAR.App.lang.getAppString('LBL_MODULE');

For more information, please refer to the app.lang.getAppString section of the Languages page.

$app_list_strings

To access $app_list_strings in Sidecar, use app.lang.getAppListStrings:

  app.lang.getAppListStrings('sales_stage_dom');

To access $app_list_strings in your browser's console, use SUGAR.App.lang.getAppListStrings:

  SUGAR.App.lang.getAppListStrings('sales_stage_dom');

For more information, please refer to the app.lang.getAppListStrings section of the Languages page.