Localization

About Localization

Localization is the process whereby a user interacts with platform using their preferred language and data formats.

The AgileApps Cloud platform Locale Settings provide a choice of data formats:

• My Settings > Locale Information - Formats chosen by the user for dates, times, and numbers, plus language.
• User Settings - Formats set for the user by the admin.
• Company Information Settings - Default user formats, and the Currency format, which can be changed only by an admin.

Considerations

• The Translation Workbench can be used to add additional languages.
• If a user's permissions don't allow them to change their personal settings, then the default settings chosen by the company are effectively fixed.

Working with Localized Values

Interface Interactions

When working with the platform GUI, data is typically displayed and entered in User Format, as determined by the user's Locale Settings. In particular, those settings are used for:

• Dates and times
• Numeric data (currencies, numbers, numbers with decimals, and percentage values)
• Formula Fields that return numeric data
• Rollup Summary Fields that accumulate numeric data

There are exceptions, however:

• When specifying numeric values that will be used in a direct comparison against database data.
  In those cases, the Database Format must be used:
• Entering Search data
• Specifying Filter Criteria for a View

• Numeric data entered in Web Forms must also be in Database Format.

• Numeric data in files generated by an Export are in Database Format.

• Numeric data that is displayed as part of a Record Identifier appears in Database Format.

Note: Dates and Times are always specified in the User's preferred format, regardless of context.

Rules and Imports

The Database Format for numeric values must be used when:

• Specifying numeric values for a Rule

Ideally, that format will also be used when:

• Supplying numeric data for an Import operation

Exceptions:

• In a Pre-import Rule, numeric data is not coming from the database. In that context, the raw data is available, exactly as it appears in the incoming data. If the numeric data is in localized form, the Java Localization Functions could be used to convert the numeric fields to Database Format. (A method needs to be defined to use them in a Java Class, The method can then be invoked by a Rule action to do convert the numeric data. Or you can save yourself the effort by ensuring that incoming numeric data is in Database Format.

• Incoming Data and Time values are always presumed to be in User Format

Java Programming

Most Java programming entails dealing with the database, which means that data provided in the APIs and returned from them are in Database Format -- except for dates and times, whose format are determined by the combination of the Field settings and the user's Locale Settings.

However, in a JSP Page, data entered by a user will generally be localized, as will the data displayed to the user. To convert between those user format and the database format, use the Java Localization APIs.

Note: The localization format is determined by the user who invokes the conversion method. So the same method produces appropriate results for different users.

REST Programming

When using the REST API, all data is specified in Database Format:

Field	Format
Date, DateTime, Time	UTC Format
Currency, Number, Number with Decimal, Percent	No currency symbol or percent sign No grouping characters (e.g. commas) in whole-number portion A decimal point (.) before fractional portion Ex: 84954.32
Lookup	The Record ID of a record in the target object. Ex: 123A456B78
Multi Object Lookup	An Object ID, to identify the target object, a colon, and a Record ID. Ex: 849Z:123A456B78

JavaScript Programming

In general, when coding Field Scripts and Form Scripts, form data will be in the User Format. Coders need to be aware of that fact when doing conversions and calculations, and when entering data into the form -- as the platform expects data coming from the form to be in that format.

However, if the code uses AJAX and REST to interact with the platform, the data going to the platform must be in Database Format, as will the data coming back. That format applies to dates and times, as well as numeric data.

To convert between the formats, use the JavaScript Localization Functions.

Template Programming

Most template variables are simply inserted into the template, for inclusion in the final document or email message. Template variable data, therefore, is in User Format.

However, sophisticated template developers may use the Velocity programming language to vary the template content based on record data. (The exception is a JSP Page-based template, which uses the Java API described above to access record data.)

When coding a conditional comparison in Velocity, the condition needs to account for the fact that the record data is in User Format. The mechanism for doing so is the Template Class, which lets you process the data values before they are seen by the template.

With such a class, you can add a new template variable to the record, after using the Java Localization Functions to convert record data to Database Format, or to convert the comparison value to User Format. (Either way works. In the end, you wind up comparing apples and apples, or oranges and oranges, depending on which conversion you decided to do.)

Learn more: Customizing Data Sent to the Template with a Document Template Class

(The same mechanism is used for an Email Template)