CFML Reference

SetLocale

Description

Sets a country/language locale option for a ColdFusion application user; the setting persists for the current ColdFusion application session. The locale value encapsulates a set of attributes that determine the default display format of date, time, number, and currency values, according to language and regional conventions.

For information about determining the locale value, see "GetLocale".

Return value

An element from the list of locales that ColdFusion supports, as a string.

Category

International functions, System functions

Syntax

SetLocale(new_locale) 

See also

GetHttpTimeString, GetLocale

History

New in ColdFusion MX:

• This function might return a different value than in earlier releases. This function uses Java standard locale determination and formatting rules on all platforms.
• The Spanish (Mexican) locale option is deprecated. Do not use it in new applications. It might not work, and it might cause an error, in later releases. (The Spanish (Modern) option now maps to Spanish (Standard).)

Parameters

Parameter	Description
new_locale	The name of a locale; for example, "en_US" (English, United States)

Usage

This function uses Java standard locale formatting rules on all platforms.

A locale value can be explicitly set in the following ways:

• From the command line; for example: java -Duser.language=de -Duser.region=DE.
• In JSP code; for example: response.setLocale ( new Locale( "de", "DE") )
• With the SetLocale function; for example: SetLocale ("German (Standard)"

The locale value persistence and usage hierarchy is as follows:

• When the locale is set explicitly, its value persists until the ColdFusion server is stopped. ColdFusion accesses this value.
• The ColdFusion Server operating system default locale value persists permanently. If the value has not been explicitly set and stored in the JSP request object, ColdFusion uses this value.
• If the operating system does not have a default value or the value is not one that ColdFusion supports, ColdFusion uses the value English (US).

ColdFusion supports the following locale options. You can use either the ColdFusion locale name or the Java standard locale string.

ColdFusion locale name	Java standard locale string
Chinese (China)
Chinese (Hong Kong)
Chinese (Taiwan)
Dutch (Belgian)	nl_be
Dutch (Standard)	nl_NL
English (Australian)	en_AU
English (Canadian)	en_CA
English (New Zealand)	en_NZ
English (UK)	en_GB
English (US)	en_US
French (Belgian)	fr_BE
French (Canadian)	fr_CA
French (Standard)	fr_FR
French (Swiss)	fr_CH
German (Austrian)	de_AT
German (Standard)	de_DE
German (Swiss)	de_CH
Italian (Standard)	it_IT
Italian (Swiss)	it_CH
Japanese	ja_JP
Korean	ko_KR
Norwegian (Bokmal)	no_NO
Norwegian (Nynorsk)	no_NO_nynorsk
Portuguese (Brazilian)	pt_BR
Portuguese (Standard)	pt_PT
Spanish (Modern)	es_ES
Spanish (Standard)	es_ES
Swedish	sv_SE

Note:   ColdFusion uses the Spanish (Standard) formats for Spanish (Modern) and Spanish (Standard).

This function can restore a locale setting by referencing the session variable that stores a locale, as follows:

<cfset oldlocale = SetLocale("localename")>

Note:   The variable server.ColdFusion.SupportedLocales is initialized at startup with a comma-delimited list of the locales that ColdFusion and the operating system support. If it is called with a locale that is not in the list, SetLocale fails.

Example

<h3>SetLocale Example</h3>
<p>SetLocale sets the locale to the specified new locale for the current session.
<p>A locale encapsulates the set of attributes that govern the display and
formatting of date, time, number, and currency values.
<p>The locale for this system is <cfoutput>#GetLocale()#</cfoutput>
<p><cfoutput><I>the old locale was #SetLocale("English (UK)")#</I>
<p>The locale is now #GetLocale()#</cfoutput>

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments