Considerations for Adopting the ICU Locale Formats

Why Is Salesforce Making This Change?

Before Winter ’20, new Salesforce orgs used the locale formats included with Oracle’s Java Development Kit (JDK). This solution worked well, but it has a few issues. Most importantly, the JDK locale formats aren’t consistent with internationalization best practices, and these JDK formats aren’t updated regularly.

ICU is an international standard, maintained and governed by a global community. The new formats provide a consistent experience across the Salesforce platform and improve integration with ICU-compliant applications across the globe. By adopting the ICU locale formats, we keep Salesforce—and your business on Salesforce—up to date with these international standards.

Don’t Wait for Salesforce Enablement

Salesforce orgs created in Winter ’20 or later have ICU locale formats enabled by default. Orgs that haven’t already switched to ICU locale formats are encouraged to manually update.

Use the Enable ICU Locale Formats release update on all orgs whose Apex Classes, Apex Triggers, and Visualforce Pages are all using API version 45 or higher. Locales control the formats for dates, times, currencies, addresses, names, and numeric values. Moving from JDK to ICU locale formats can affect your users and cause misinterpretation of data. For this reason, we recommend that customers using JDK locale formats test and enable this change before it’s enforced.

Test in a Sandbox

Before you enable the ICU locale formats in your production org, try them out in a sandbox org with API version 45.0 or higher. Testing in a sandbox can uncover any issues with custom code and third-party integrations.

Impact of Adopting a New API Version

For best results with the ICU locale formats, Apex classes, Apex triggers, and Visualforce pages that reference locale formats, use API version 45.0 or later. If your org contains items on API version 44.0 or earlier, update the API version to avoid data integrity issues and end-user confusion.

Updating the API version can include structural and behavior changes for objects and other code components. For example, the update can include new fields on an object, removal of a field, and changed behavior. We recommend upgrading the API version and completing thorough testing of all related functionality in a sandbox before you update production.

ICU and Inline Edits on Visualforce Pages

Inline edits on Visualforce pages always use the latest API version. Because of that behavior, when ICU is enabled, inline edits on Visualforce pages always use ICU locale formats, regardless of the page's API version. When a user makes an inline edit on a Visualforce page on API version 44.0 or earlier and saves their changes, the user can receive a ParseException error. For example, "Invalid Date and Time." These errors don't cause data integrity issues, but the errors can frustrate users.

To avoid these errors when ICU is enabled, ensure that your custom Visualforce pages use API version 45.0 or later.

Installed Packages

Before you start testing, check with your package providers to make sure that all your installed packages are compatible with the ICU locale formats. If your package provider indicates that a fix for one of your installed packages is pending, factor that into your testing and activation timeline.

If you’re a package provider, update the Apex classes, Apex triggers, and Visualforce pages in your packages to API version 45.0 or later. Update any custom code that requires or passes data in specific locale formats. Then test your packages in an org with ICU enabled. Verify that all changed formats appear as expected, and update your code as needed.

Custom Code

Many orgs contain custom code. Lightning Components allow you to customize Lightning Experience, the Salesforce mobile app, or to build your own standalone apps. With Apex, the options are even broader.

Apex is often used to:

• Create Web services.
• Create email services.
• Perform complex validation over multiple objects.
• Create complex business processes that aren’t supported by workflow.
• Create custom transactional logic, which occurs over the entire transaction, not just with a single record or object.
• Attach custom logic to another operation. For example, attach custom logic to saving a record, so that it occurs whenever the operation is executed, regardless of where it originates in the user interface.

Also consider formula fields and areas where you can customize filters, such as object lookups. To search your Salesforce code, download the metadata. Then use a command-line interface such as Salesforce CLI.

For more information on the steps to take to review and update your custom code, see Custom Code and Locale Format Changes in Salesforce Help. This section also provides examples of errors that can occur when custom code relies on specific date, time, and currency formats. Use this information to understand how to test custom functionality.

If an external developer or consultant created your custom code and you don’t have a developer who can perform the assessment, start by testing the custom functionality. If you find issues, consider contracting with an external developer or consultant to assist with the evaluation of the custom code in your org.

Notify Your Users and Partners

Let your users know when you plan to enable ICU in production and how the new locales can affect them. Otherwise, the differences between JDK and ICU locale formats can cause confusion.

For example, with the Spanish (Honduras) locale, the short date format changes from MM-dd-yyyy to dd-MM-yyyy when you enable the ICU locale formats. Make sure that your users know about this change, or they can interpret 01-11-2021 as January 11, 2021 instead of November 1, 2021.

Reaching everyone can require multiple reminders before and after you enable ICU in production.

Also consider notifying your partners, especially if those partners send information to or extract information from Salesforce. Resolving issues related to integrations can require their assistance.

Use of Locale Formats

We provide a list of all possible locale formats, but not all formats are used in Salesforce. For example, almost all dates on standard Salesforce screens use the short date format, which can’t be modified on standard screens.

Likewise, not all formats are available for use in custom code. In particular, the medium date format isn’t available in Apex at this time.