Salesforce Docs Portal

Use Locale-Neutral Methods in Code

Data formats can change based on the user’s locale, adoption of new standards, or updates to the standard locale formats. To avoid errors when a locale format changes, use standard methods to handle this data in your code. If your code formats the data using the user’s locale, apply the format after all other processing is complete.

Required Editions

Available in: both Salesforce Classic and Lightning Experience
Available in: all editions

To search your Salesforce code, download the metadata. Then use a command-line interface such as Salesforce CLI.

A user’s locale determines the formats for these types of data: address, currency, date, datetime, name, integer, and time. The start day of the week is also based on the user’s locale.

When you migrate from Oracle’s Java Development Kit (JDK) locale formats to the International Components for Unicode (ICU) locale formats, the currency, date, datetime, integer, and time formats change for some locales.

Also, locale formats are regularly updated to match the newest international standards. And users can update their locale to match their current location or preference.

To prevent issues with your custom code due to locale format changes, follow these guidelines.

  • Use standard methods to call these formats. For example, when handling dates in Apex, use the Date data type.
  • When handling these data types in your code, use standard methods to extract components. For example, when you want to extract the month from a date format in Apex, use the month() method on the Date class. Similarly, handle integers and currency values as unformatted integers until you must format them.
  • If your code performs additional processing on a value, use a locale-neutral format. For example, in Apex, use format(string dataFormat) or format(string dataFormat, string timezone).
  • Make the transformation of data to the user’s preferred locale format the last step in handling that data. For example, when calculating a future date in Apex, use the format() method of the Date class after the calculation.
  • Apex format() methods, such as DateTime.format() return values in the context user’s locale. If subsequent code expects data in a particular locale format, specify the format explicitly. For example, to pass a time in a format such as 10:15 a in Apex, use DateTime.format('h:mm a'). Because this example passes the string argument 'h:mm a' to the format function, the datetime is formatted according to the supplied format regardless of the context user’s locale.
  • When constructing delimited lists, put any locale data that can contain a comma in quotes.

Here are some examples of code that return formats in the user’s preferred locale format.

  • Apex: the format() method in the Date, DateTime, and Integer classes
  • Aura Lightning Components: the $Locale global variable
  • Lightning Web Component Internationalization properties

See Also