A locale identifies the exact language and cultural settings to use for a user. The locale controls how to format the following:
- Dates
- Times
- Numbers
- Currency amounts
ColdFusion supports all locales supported by the JVM that it uses.
Current JVM versions (through 1.4.2) do not support localized numbers such as Arabic-hindic numbers used in Arabic locales or hindic digits used in Hindi locales. ColdFusion uses Arabic numbers in all locales.
Locale names
ColdFusion supports two formats for specifying locale names: the standard Java locale names and the ColdFusion naming convention that was required through ColdFusion 6.1.
- You can specify all locales using a name consisting of the following:
- Two lowercase letters to identify the language; for example, en for English, or zh for Chinese.
- Optionally, an underscore and two uppercase letters to identify the regional variant of the language; for example, US for the United States, or HK for Hong Kong SAR of China. For example, en_US represents United States English and es_MX represents Mexican Spanish. For a list of the Java locale identifiers supported in the Sun 1.4.2 JVM and their meanings, see https://docs.oracle.com/javase/7/docs/api/java/util/Locale.html.
Previous to ColdFusion MX 7, ColdFusion supported a limited set of locales, and used identifiers that consisted of the name of the language, followed, for most languages, by a regional identifier in parentheses, such as English (US) or German (Standard). ColdFusion continues to support these names; for a list, see SetLocale in the CFML Reference.
The Server.coldfusion .supportedlocales variable is a comma-delimited list of the locale names that you can specify.
ColdFusion also includes a GetLocaleDisplayName function that returns a locale name in a format that is meaningful to users. It lets you display the locale using words in the user's language; for example, francais (France).
Determining the locale
ColdFusion determines the locale value as follows:
By default, ColdFusion uses the JVM locale, and the default JVM locale is the operating system locale. You can set the JVM locale value explicitly in ColdFusion in the JVM Arguments field on the Java and JVM Settings page in the ColdFusion Administrator; for example:
-Duser.language=de -Duser.country=DE.
- A locale set using the SetLocale function persists for the current request or until it is reset by another SetLocale function in the request.
- If a request has multiple SetLocale functions, the current locale setting affects how locale-sensitive ColdFusion tags and functions (such as the functions that start with LS) format data. The last SetLocale function that ColdFusion processes before sending a response to the requestor (typically the client browser) determines the value of the response Content-Language HTTP header. The browser that requested the page displays the response according to the rules for the language specified by the Content-Language header.
- ColdFusion ignores any SetLocale functions that follow a cfflush tag.
Using the locale
The SetLocale function determines the default formats that ColdFusion uses to output date, time, number, and currency values. You use the GetLocale function to determine the current locale setting of ColdFusion, or you can use the GetLocaleDisplayName function to get the locale name in a format that is meaningful to users. If you have not made a call to SetLocale, GetLocale returns the locale of the JVM.
The current locale has two effects:
- When ColdFusion formats date, time, currency, or numeric output, it determines how to format the output. You can change the locale multiple times on a ColdFusion page to format information according to different locale conventions. This enables you to output a page that properly formats different currency values, for example.
- When ColdFusion returns a page to the client, it includes the HTTP Content-Language header. ColdFusion uses the last locale setting on the page for this information.
In earlier versions of ColdFusion, the default locale was always English, not the operating system's locale. For the Japanese version of ColdFusion, the default was Japanese.
The following example uses the LSCurrencyFormat function to output the value 100,000 in monetary units for all the ColdFusion-supported locales. You can run this code to see how the locale affects the data returned to a browser.
<!--- loop through list of locales; show currency values for 100,000 units ---> <cfloop LIST = "#Server.Coldfusion.SupportedLocales#" index = "locale" delimiters = ","> <cfset oldlocale = SetLocale(locale)> <cfoutput><p><b><I>#locale#</I></b><br> Local: #LSCurrencyFormat(100000, "local")#<br> International: #LSCurrencyFormat(100000, "international")#<br> None: #LSCurrencyFormat(100000, "none")#<br> <hr noshade> </cfoutput> </cfloop>
This example uses the ColdFusion variable Server.Coldfusion.SupportedLocales, which contains a list of all supported ColdFusion locales.