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:
- 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.
- If there is no Display Culture String set, use the Display Name value (displayName).
- 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.
//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.
ValueLocalized is set based on the following rule:
- 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:
- 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
Retrieve a Localized String By Base String
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,