Labels and Lists

Overview

How to work with the application language framework. More information on working wth the module language framework can be found in the Language section under Module Framework.

Language Keys

As Sugar is fully internationalized and localizable, each language is defined by a unique language key. The language keys will prefix any files dealing with languages. An example of a language key is ‘en_us’ which is used for English (US). For more information regarding please refer to the Language Keys section.

Application Label Framework

$app_list_strings / $app_strings

The $app_list_strings contains the various drop down lists for the system while $app_strings contains the system application labels. The initial set of definitions can be found in the following directory:

./include/language/<language key>.lang.php

As you begin working within the system and deploying modules and lists through Studio, any changes to these labels will be reflected in the corresponding custom directory:

./custom/include/language/<language key>.lang.php

Customizing Labels and Lists

If you are developing a customization and want to be able to create or edit existing label/list values, you will need to work within the extension application directory. To do this you will create a file as follows:

./custom/Extension/application/Ext/Language/<language key>.<unique name>.php

The file will contain your override values. Please note that within this file you will set each label index 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, you will then 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’. In using this function, the label will be retrieved for the current users language. This function 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'];
}

Retrieving Lists

There are two ways to retrieve a list. The first is to use the ‘translate’ function found in ‘include/utils.php’. In using this function, the label will be retrieved for the current users 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'];
}

Accessing Language Pack Strings with JavaScript

All language pack strings are accessible within the browser-side JavaScript. Use the following JavaScript call to access these strings:

// LBL_LOADING string stored in 
$app_stringsSUGAR.language.get('app_strings', 'LBL_LOADING');

These JavaScript language files are cached. Rebuild the JavaScript files from the Repair console in the Admin section if the language files are changed. This removes the cache files and rebuilds the JavaScript files when needed. It also increments js_lang_version in sugar_config to recache the JavaScript files in the user’s browser.