\HeaderA{locales}{Query or Set Aspects of the Locale}{locales}
\aliasA{Sys.getlocale}{locales}{Sys.getlocale}
\aliasA{Sys.setlocale}{locales}{Sys.setlocale}
\keyword{utilities}{locales}
\begin{Description}\relax
Get details of or set aspects of the locale for the \R{} process.
\end{Description}
\begin{Usage}
\begin{verbatim}
Sys.getlocale(category = "LC_ALL")
Sys.setlocale(category = "LC_ALL", locale = "")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{category}] character string.  The following categories should
always be supported: \code{"LC\_ALL"},
\code{"LC\_COLLATE"}, \code{"LC\_CTYPE"}, \code{"LC\_MONETARY"},
\code{"LC\_NUMERIC"} and \code{"LC\_TIME"}.  Some systems
will also support \code{"LC\_MESSAGES"}, \code{"LC\_PAPER"}
and \code{"LC\_MEASUREMENT"}.

\item[\code{locale}] character string.  A valid locale name on the system in
use.  Normally \code{""} (the default) will pick up the default
locale for the system.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The locale describes aspects of the internationalization of a program.
Initially most aspects of the locale of \R{} are set to \code{"C"} (which
is the default for the C language and reflects North-American usage).
\R{} sets \code{"LC\_CTYPE"} and \code{"LC\_COLLATE"}, which allow the
use of a different character set and alphabetic
comparisons in that character set (including the use of
\code{\LinkA{sort}{sort}}), \code{"LC\_MONETARY"} (for use by
\code{\LinkA{Sys.localeconv}{Sys.localeconv}}) and \code{"LC\_TIME"} may affect
the behaviour of \code{\LinkA{as.POSIXlt}{as.POSIXlt}} and \code{\LinkA{strptime}{strptime}}
and functions which use them (but not \code{\LinkA{date}{date}}).

\R{} can be built with no support for locales, but it is normally
available on Unix and is available on Windows.

The first seven categories described here are those specified by
POSIX.  \code{"LC\_MESSAGES"} will be \code{"C"} on systems that do not
support message translation, and is not supported on Windows.  Trying
to use an unsupported category is an error for \code{Sys.setlocale}.

Note that setting \code{"LC\_ALL"} sets only \code{"LC\_COLLATE"},
\code{"LC\_CTYPE"}, \code{"LC\_MONETARY"} and \code{"LC\_TIME"}.

Attempts to set an invalid locale are ignored.  There may or may not
be a warning, depending on the OS.

Attempts to change the character set (by
\code{Sys.setlocale("LC\_TYPE", )}, if that implies a different
character set) during a session may not work and are likely to lead to
some confusion.
\end{Details}
\begin{Value}
A character string of length one describing the locale in use (after
setting for \code{Sys.setlocale}), or an empty character string if the
current locale settings are invalid or \code{NULL} if locale
information is unavailable.

For \code{category = "LC\_ALL"} the details of the string are
system-specific: it might be a single locale name or a set of locale
names separated by \code{"/"} (Solaris, Mac OS X) or \code{";"}
(Windows, Linux).  For portability, it is best to query categories
individually: it is not necessarily the case that the result of
\code{foo <- Sys.getlocale()} can be used in
\code{Sys.setlocale("LC\_ALL", locale = foo)}.
\end{Value}
\begin{Section}{Warning}
Setting \code{"LC\_NUMERIC"} may cause \R{} to function
anomalously, so gives a warning.  As from \R{} 2.7.0 input conversions
in \R{} itself are unaffected, but the reading and writing of ASCII
\code{\LinkA{save}{save}} files will be, as may packages.
Setting it temporarily to produce graphical or text output may work
well enough, but \code{\LinkA{options}{options}(OutDec)} is often preferable.
\end{Section}
\begin{SeeAlso}\relax
\code{\LinkA{strptime}{strptime}} for uses of \code{category = "LC\_TIME"}.
\code{\LinkA{Sys.localeconv}{Sys.localeconv}} for details of numerical and monetary
representations.

\code{\LinkA{l10n\_info}{l10n.Rul.info}} gives some summary facts about the locale and
its encoding.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
Sys.getlocale()
Sys.getlocale("LC_TIME")
## Not run: 
Sys.setlocale("LC_TIME", "de")     # Solaris 7: details are OS-dependent
Sys.setlocale("LC_TIME", "de_DE.utf8")  # Modern Linux etc.
Sys.setlocale("LC_TIME", "German") # Windows
## End(Not run)
Sys.getlocale("LC_PAPER")          # may or may not be set

Sys.setlocale("LC_COLLATE", "C")   # turn off locale-specific sorting
\end{ExampleCode}
\end{Examples}

