Localization in Aptify Web

Aptify provides a framework to localize strings based on the current User's Culture.  Starting with Aptify 5.5.3, Aptify Web includes the localization framework.  You can retrieve the local string, based on the current User's Culture, in Aptify Web using the Name of the Culture String (preferred) or its Base String.  In Aptify 5.5.3, the support for localization has been implemented in some areas but not all.  Future releases will expand localization support throughout the core Framework and Applications.  New Product development and configurations should be built with localization support.

Localization How To

Localized Display Names for Entities and Entity Fields

A new property, displayNameLocalized, has been added to the Entity metadata and EntityField metadata objects in Aptify Web.  Use these properties to return the localized Display Name for Entities and Entity Fields.

displayNameLocalized is set based on the following rules:

1. Does the record have a Display Culture String set?  If yes, retrieve the Local String value for that Culture String, based on the current User's Culture.  The Base String will be the Display Name (displayName) value.  In the rare case where Display Name is not set, the Name (name) value will be used as the Base String. If no, proceed to step 2.
2. If there is no Display Culture String set, use the Display Name value (displayName).
3. If there is no Display Name set, use the Name value (name).

//If you already know the Entity metadata has been loaded, which is assured in Form Template Layout controls or in a client-side Generic Entity plug-in, you can use findByName, which is a synchronous call.  If you can't be sure, you need to use the loadEntity method and provide a callback, which turns the operation into an asynchronous operation.
 
//Get the Persons Entity metadata object and store it in personsMD.
var personsMD = Aptify.framework.metaData.entities.findByName('Persons');
 
var personsLocalizedDisplayName = personsMD.displayNameLocalized;
 
//Get the NameWCompany Entity Field metadata object from the Persons Entity Metadata.
var nameWCompanyFieldMD = personsMD.fields.findByName('NameWCompany');
 
var nameWCompanyLocalizedDisplayName = nameWCompanyFieldMD.displayNameLocalized;

Get Localized Entity Display Name (Alternate)

Another way to get the localized Display Name for an Entity is to use the method, Aptify.framework.metaData.entities.getDisplayName, which accepts the Name of the Entity as a parameter and returns the localized Display Name.

//Return the localized display name for the Persons Entity and store it in sPersonsDisplayName.
var sPersonsDisplayName = Aptify.framework.metaData.entities.getDisplayName('Persons');

Localized Entity Field Values

The static list of Entity Field Values (EntityFieldValues is a sub-type of EntityFields).  The Value and Description fields support localization based on the optional fields Value Culture String ID and Description Culture String ID.  the properties ValueLocalized and DescriptionLocalized have been added to the FieldValue (fieldValue) object in Aptify Web.  The Combo Box Form Component has been updated to use the localized Value.

ValueLocalized is set based on the following rule:

1. Is Value Culture String ID set?  If yes, retrieve the Local String value for that Culture String, based on the current User's Culture.  The Base String will be the Value.  If no, use the Value.

DescriptionLocalized is set based on the following rule:

1. Is Description Culture String ID set?  If yes, retrieve the Local String value for that Culture String, based on the current User's Culture.  The Base String will be the Description.  If no, use the Value.

Retrieve a Localized String By Culture String Name

Aptify.framework.utility.cache.getCultureLocalString is the method that is used to return the localized string based on the Culture String Name and Base String.  This method accepts an object.  The Name of the Culture String is populated in the stringName property and the Base String is populated in the baseString property.  The Culture is defined by the currently logged in User's CultureId.  If Culture ID is passed into the method, it will be ignored.  If the User doesn't have a defined Culture, the system's Built-in Culture is used.

//Find the Culture String with the Name 'Global.Favorites' and return the localized string.  
//'Favorites' is the baseString that will be used if no match is found or if there is no Local String for the User's Culture.
var localizedFavorites = Aptify.framework.utility.cache.getCultureLocalString({
	stringName:  'Global.Favorites',
	baseString:  'Favorites'
});

Retrieve a Localized String By Base String

Aptify.framework.utility.cache.getCultureLocalString is the method that is used to return the localized string based on the Base String.  This method accepts an object.  Only the baseString property should be provided for a lookup on Base String.  If stringName is provided, it will be used for the match.  Using stringName for the match is the preferred approach.

//Find the Culture String using the Base String.  Base String is not guaranteed to be unique so the first match will be used.
//Use the Base String 'Favorites'.  Note that stringName is not provided.  If stringName is provided, it will be used for the Culture
//String match.  Using stringName to match on Culture String Name is preferred.  The Base String match is used by some core Form Components
//and has been kept for backwards compatibility.
//'Favorites' is the baseString that will be used if no match is found or if there is no Local String for the User's Culture.

var localizedFavorites = Aptify.framework.utility.cache.getCultureLocalString({
	baseString:  'Favorites'
});

Localization Metadata

The metadata for localization is found under the Localization Application in the Cultures and Culture Strings Entities.  There is also a link to a Cultures record in the Users Entity.  

Cultures Entity

Defines the Cultures supported in the database.  For localization, each Culture will be listed in the Culture String's Local Strings sub-type, allowing a Local String value to be entered for each Culture.

Culture Strings Entity

The repository of all localizable strings in Aptify and the local strings for each culture.  Culture Strings have a unique Name and a Base String.  The Name is used as the primary lookup.  The Base String is the default value for the string and matches the local string for the Built-in Culture (see below for information about the Built-in Culture).  There is a Local Strings sub-type that lists all Cultures defined in Aptify.  A Local String should be provided for each Culture where the Local String does not match the Base String.  If the Local String matches the Base String, it can be left blank.  When no Local String exists or no Culture String is found, the Base String will be used.

Users Entity

The User's CultureID defines the Culture for the current User.  Users.CultureID is a linked Entity field to the ID field in Cultures. It is not required but there is a default value which is set to 1 (EN) in the core Product.  If the Users record does not have a CultureID defined, the Built-in Culture is assumed for that User.

Built-in Culture

The built-in Culture is the default Culture in Aptify.  All strings that support localization have a Base String.  The Base String is the default value that is used if the local string (or Culture String record) doesn't exist.  The Base String is the current local string for the built-in Culture.  In core Aptify, the Built-in Culture is EN and has an ID of 1.  Changing the Built-in Culture requires the Culture Strings' Base String values to be updated to match the new Culture.  It also requires the Display Name values stored with many Entity records, link Entities, Entity Fields, to be updated to match the new Culture.

The benefit of having a Built-in Culture is that it significantly reduces overhead related to localization.  When a User's Culture is the Built-in Culture, the Base String can be returned immediately.  There is no need to download the Local Strings and there is no need to perform the local string lookup.  Most Aptify Users belong to the Built-in culture so it makes sense to optimize for the Built-in Culture,

The Built-in Culture ID value is stored at Aptify.framework.configuration.builtInCultureId.  This property is defined at an internal Framework Configuration attribute.  This is stored in the minified javascript.  In the non-minified source code it is stored in Aptify.Framework.Configuration.Internal.js.