In this document, you will learn about the following topics:
- Why is setting a Locale important when working with Pega platform
- Functionality Affected by Locale Settings
- How Locale affects the use of Calendars
- Diagnosing and debugging Calendar issues
Introduction
Calendar controls focus specifically on date selection and provide a visual calendar interface for users to pick dates. This control is optimized for scenarios where only date information is required, such as selecting birth dates, project due dates, or event dates. The Calendar control offers an intuitive month-and-year navigation experience and can be configured to restrict selections to valid dates by disabling specific days like weekends or holidays.
Why is setting a Locale important when working with Pega platform?
Setting a locale in the Pega Platform serves several critical functions that directly impact user experience and application functionality. The locale determines the language settings of the application, which is fundamental for internationalization efforts. This becomes particularly valuable when developing applications for global audiences, as it allows users to interact with the application in their preferred language, significantly improving user satisfaction and reducing errors that can occur when users struggle to understand application content.
Browser language vs. locale or country suffix
While browser language is determined by the user's browser configuration, Pega's locale system provides a more sophisticated approach to language management.
The Pega Platform follows a specific hierarchy when determining locale: it first examines the locale selected in the current browser, but if the operator profile specifies a different locale, the platform uses the profile locale instead. This means that even when a user's browser is set to one language, Pega can display the application in the language specified in their user profile, providing a more tailored and consistent experience.
This dual approach offers significant flexibility - it allows for automatic detection based on browser settings while providing administrators and users the ability to override these settings when needed. You can also temporarily override locale settings programmatically using the PublicAPI method setLocale(), which remains valid until the user session ends, or another call to the method is made.
Locale definition in terms of Pega calendars
When it comes to Pega calendars, locale settings play a crucial role in determining how dates and times are displayed and formatted throughout the application. The platform uses Unicode standards for date and time patterns, which means it can handle various formatting conventions based on the selected locale.
Pega Platform uses the International Components for Unicode (ICU) locale format standards for date and time patterns.
ICU focuses on locale-aware formatting for user display. It provides comprehensive support for presenting dates and times according to regional conventions - for example, displaying "MM/DD/YYYY" for US users while showing "DD/MM/YYYY" for UK users.
External Factors that influence Locale Behavior
Implementation of locale-specific behaviors depends on the Java Virtual Machine version that supports the system. This means that many of the locale-specific behaviors are inherited from the underlying Java implementation.
Locales generally do not impact controls except in cases involving formatting, such as dates, dateTime, and currency. For these specific locales, we adhere strictly to ISO standards.
ISO standards, particularly ISO 8601, provide standardized, language-neutral formats primarily designed for data storage and system communication. The familiar "YYYY-MM-DD" format exemplifies this approach, ensuring consistency across different systems and eliminating ambiguity in data exchange.
Functionality Affected by Locale Settings
The locale configuration impacts several critical areas of Pega functionality:
Date and Time Processing
- Incorrect locale settings can cause "is not a valid date/time" errors, particularly with locales that have specific formatting requirements
- Date picker controls and calendar widgets rely on proper locale configuration for validation
User Interface Localization
- If no Ruleset exists for the selected locale, the UI defaults to English
- Field labels, buttons, and prompts are localized based on available language packs
- Right-to-left language support for Arabic and similar languages
Data Formatting and Validation
- Number formatting and decimal separators
- Currency display and calculations
- Time zone handling and daylight-saving time implementation
This article will focus solely on how Locale affects the use of Calendars.
Date and Time Processing - Calendar control
When users interact with calendar components, Pega automatically formats dates and times according to their locale preferences. This includes not only the visual arrangement of day, month, and year, but also considerations for different calendar systems (such as the Thai solar calendar that Pega specifically supports), time zone handling, and cultural conventions around business days and holidays.
Pega determines the calendar to use based on:
- The locale selected in the user's browser
- The locale specified in the operator's profile (which overrides the browser locale)
- Any temporary locale settings applied via the PublicAPI method
setLocale() - Schedule tab configuration
See the Pega Documentation Completing the Schedule tab which highlights the use of the ‘Calendar Locale’ setting to identify the industry standard used:
"Specifies the locale in which the starting date of the calendar is parsed. This setting is relevant for locales that use non-Gregorian calendars, such as the Thai Buddhist or Japanese Imperial calendars"
Diagnosing and debugging Calendar issues
Scenario 1
-
Current Date time function returns 2568 year for Thailand locale
Explanation
Thailand uses ISO 8601 as its national standard for date and time representation, which is TIS 111:2535. The formal date format in Thailand is D/M/YYY but they also use the Thai Buddhist Era (BE) which 543 years ahead of the Gregorian calendar, so 2025 AD corresponds to 2568 BE.
When using the Thai locale (th_TH) it uses this offset of the Thai solar calendar (also known as the Buddhist calendar).
Additional steps are required to configure the Pega Calendar.
The Thai calendar configuration involves a specific technical implementation where developers add a JavaScript script to the HTML fragment (pegaUtils.useBuddhistThaiSolarCalendar = true) and configure the locale settings to Thai (Thailand, TH) with the Asia/Bangkok time zone.
This ensures that the Date Time control accurately reflects the Thai calendar system while maintaining full functionality within Pega applications.
See Configuring the Thai calendar.
Scenario 2
-
Norwegian browser locale shows date values as ‘undefined’
See known issue Norwegian locale displays date control values as undefined
Explanation
In the latest Pega releases, Locale support has been added for Ireland ('ga', 'ga_IE' ), Sweden ('en_SE'), and Norway ('nb','nb_NO').
In addition, logging has been enhanced in datetime to better determine if a locale is invalid or missing if an IllegalArgumentException is generated in the PDC.
Scenario 3
-
Arabic locale displays date control values as ‘undefined’
See known issue Arabic locale displays date control values as undefined.
Explanation
In the latest Pega releases this has been resolved by correcting the number conversion and formatting for the necessary values.
Scenario 4
-
ar_SA locale is not converting the calendar to Hijri
Expectation: The calendar displays dates according to the Hijri calendar. User expects Calendar to display 2021 as 1442 using the Hijri conversion.
Current behavior: The calendar displays the year as 2021 according to Gregorian calendar.
Explanation
The Hijri calendar needs special handling for year calculation.
It is not a direct conversion from the Gregorian calendar because:
- It is based on lunar cycles, not solar ones.
- Each month begins with the sighting of a new crescent moon.
- A Hijri year has 354 or 355 days, making it 10–11 days shorter than a Gregorian year.
As a result, Hijri dates shift backward each year relative to the Gregorian calendar.
This calendar is not supported, and a product enhancement request has been submitted for this.
References
Internationalization and localization
Converting your UI for right-to-left languages
User interface controls and presentation
Specifying calendar navigation options
Troubleshooting DateTime issues
How BusinessCalendar functions AddDays() and AddTime() treat holidays, weekends, and time zones
Incorrect date displays for DateTime control for th_TH locale
Same DateTime property displays in different time zones