Difference between revisions of "Localization"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
 
(102 intermediate revisions by the same user not shown)
Line 1: Line 1:
==About Localization==
==About Localization==
''Localization'' is the process whereby a user interacts with platform using their preferred language and data formats.
''Localization'' is the process whereby a user interacts with platform using their preferred language and data formats.
The {{EnterpriseBrand}} Locale Settings provide a choice of data formats:
{{:Locale Settings}}
;Considerations:
:* 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==
==Working with Localized Values==
===Platform Settings===
The format you'll be working with depends on the type of data, and the context in which the data is used.
The Locale Settings
 
{{:Locale Settings}}
The following table summarizes the situations. Details are in the sections that follow.
::{| border="1" cellpadding="5" cellspacing="1"
!  !!  !! Dates and Times !! Numbers and Currency
|-
| rowspan="2" align="center"|'''GUI'''
| Search<br>Filter Criteria<br>Web Forms<br>Record Identifiers
|  align="center"|[[User Format]] ||  align="center"|[[Database Format]]
|-
| align="center"|all other || colspan="2" align="center"|[[User Format]]
 
|-
| colspan="2" align="right"|'''Import'''
| align="center"|[[Import Data#Data_Format|''Import Format'']] || align="center"|[[Database Format]]
|-
| colspan="2" align="right"|'''Export'''
| align="center"|[[User Format]] || align="center"|[[Database Format]]
 
|-
| colspan="2" align="right"|'''Formulas and Rules'''
| align="center"|[[User Format]] || align="center"|[[Database Format]]
 
|-
| colspan="2" align="right"|'''Java API''' 
| align="center"|[[User Format]] || align="center"|[[Database Format]]
 
|-
| colspan="2" align="right"|'''JavaScript'''
| colspan="2" align="center"| [[User Format]]
 
|-
| colspan="2" align="right"|'''REST API'''
| colspan="2" align="center"| [[Database Format]]
 
|-
| colspan="2" align="right"|'''Velocity Templates'''
| colspan="2" align="center"| [[User Format]]


The [[Translation Workbench]] can be used to support additional languages.
|}


===Interface Interactions===
===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]].
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.<br>In those cases, the [[Database Format]] must be used:
::* Entering [[Search]] data
::* Specifying [[HowTo:Filter a View to Restrict the Records it Displays|Filter Criteria]] for a [[View]]
 
:* Numeric data entered in [[Web Forms]] must also be in [[Database Format]].
 
:* Numeric data that is displayed as part of a [[Record Identifier]] appears in [[Database Format]].
 
{{Note|<br>'''Dates and Times''' are always specified in the User's preferred format, regardless of context.}}
 
===Rules and Formulas===
In [[Rules]], and when uing the [[Formula Builder]] to specify default field values and computed fields:
:* '''Date and Time''' values must be specified in [[User Format]]
:* Numeric values must be specified in [[Database Format]]
 
===Imports and Exports===
These formats are used for imports:
:* Numeric values are in [[Database Format]]
:* Date and Time values are in a fixed [[Import Data#Data Formats|Import Format]]: <tt>YYYY-MM-DD&nbsp;[HH:mm:ss]</tt>


There are exceptions, however. When specifying numeric values that will be used in a direct comparison against database data.<br>In those cases, the [[Database Format]] must be used:
As an option, when imported numeric data is in the user's localized format:
:* Entering [[Search]] data
:* A '''Pre-Import''' Rule can be used to convert the incoming numeric values to Database Format.
:* Specifying [[HowTo:Filter a View to Restrict the Records it Displays|Filter Criteria]] for a [[View]]
:* To do that, The [[Java Localization Functions]] are used. A method must be defined to invoke them in a Java [[Class]], The method can then be invoked by a Rule action to convert the numeric data.  
:* Supplying values for an [[Import]] operation
:* Or you can save yourself the effort by ensuring that incoming numeric data is in [[Database Format]] to start with.)
:* Specifying values in a [[Rule]] that fires ''before'' data is committed to the database.<br>(Rules that fire ''after'' data is committed see data in Database Format.)


{{Note|Dates are always specified in the User's preferred format, even when searching and filtering.}}
For exports:
:* Numeric values are in [[Database Format]]
:* Date and Time values are in [[User Format]]


===Java Programming===
===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, which are in [[User Format]], unless the [[Field Type]] is ''as entered'', rather than auto-convert.
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]].


===JavaScript Programming===
{{Note|<br>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===
===REST Programming===
When using the REST API, all data is specified in ''Database Format'':
When using the REST API, all data is specified in ''Database Format'':
{{:Database Format}}
{{:Database Format}}
===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===
For a JSP [[Page]]-based template, the Java API described above is used to access record data. In that context, Java rules apply.
In other templates, the {{^Velocity}} programming language is used.
Most template variables are simply inserted into the template, for inclusion in the final document. Template variable data, therefore, is in [[User Format]]. However, sophisticated template developers may use conditions to vary the template content based on 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 [[Document Template Class]], which lets you preprocess the list of data values, adding to it and modifying as needed, before it is seen by the template.
{{Note|Data preprocessing is not supported in [[Email Templates]].}}
With such a class, you can add a new template variable to the record, using the [[Java Localization Functions]] to convert record data to [[Database Format]]. The template can then use the same format for the comparison value, so you wind up comparing apples to apples.
Of course, you could also convert the comparison value into User Format, and compare oranges to oranges. But then the comparison value would be embedded in the code, where it is harder to change. So the recommended approach is to convert the user data to Database Format.
:''Learn more:''
:* [[Document Templates#Customizing Data Sent to the Template with a Document Template Class|Customizing Data Sent to the Template with a Document Template Class]]
:* [[Document Templates#Example: Localizing a Comparison Value|Localizing a Comparison Value]]
<noinclude>
[[Category:Application Design]]
[[Category:Development]]
</noinclude>

Latest revision as of 21:56, 11 September 2013

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:

Considerations
  • 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

The format you'll be working with depends on the type of data, and the context in which the data is used.

The following table summarizes the situations. Details are in the sections that follow.

Dates and Times Numbers and Currency
GUI Search
Filter Criteria
Web Forms
Record Identifiers
User Format Database Format
all other User Format
Import Import Format Database Format
Export User Format Database Format
Formulas and Rules User Format Database Format
Java API User Format Database Format
JavaScript User Format
REST API Database Format
Velocity Templates User Format

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:

Notepad.png

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

Rules and Formulas

In Rules, and when uing the Formula Builder to specify default field values and computed fields:

Imports and Exports

These formats are used for imports:

As an option, when imported numeric data is in the user's localized format:

  • A Pre-Import Rule can be used to convert the incoming numeric values to Database Format.
  • To do that, The Java Localization Functions are used. A method must be defined to invoke them in a Java Class, The method can then be invoked by a Rule action to convert the numeric data.
  • Or you can save yourself the effort by ensuring that incoming numeric data is in Database Format to start with.)

For exports:

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, which are in User Format, unless the Field Type is as entered, rather than auto-convert.

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.

Notepad.png

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
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

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

For a JSP Page-based template, the Java API described above is used to access record data. In that context, Java rules apply.

In other templates, the Velocity programming language is used.

Most template variables are simply inserted into the template, for inclusion in the final document. Template variable data, therefore, is in User Format. However, sophisticated template developers may use conditions to vary the template content based on 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 Document Template Class, which lets you preprocess the list of data values, adding to it and modifying as needed, before it is seen by the template.

Notepad.png

Note: Data preprocessing is not supported in Email Templates.

With such a class, you can add a new template variable to the record, using the Java Localization Functions to convert record data to Database Format. The template can then use the same format for the comparison value, so you wind up comparing apples to apples.

Of course, you could also convert the comparison value into User Format, and compare oranges to oranges. But then the comparison value would be embedded in the code, where it is harder to change. So the recommended approach is to convert the user data to Database Format.

Learn more: