# Locale methods

## convertTimestamp( timestamp, toTimeZone, fromTimeZone ) <a href="#converttimestamp" id="converttimestamp"></a>

Converts a given timestamp from one timezone to another.

* **`timestamp`** The timestamp to convert. Expected to be in the given `fromTimezone`.
* **`toTimeZone`** The desired timezone, one of the PHP constants as specified in <http://php.net/manual/en/timezones.php>. If none specified, the current [Locale](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale) timezone is used.
* **`fromTimeZone`** The timezone on which the given `timestamp` is considered to be in. If not specified the default cherrycake timezone is used, as set in [Engine::init](https://cherrycake.tin.cat/version-0.x/core-classes/engine/methods#init)

**Returns:** The converted timestamp, or `false` if it couldn't be converted.

## formatCurrency( amount, setup ) <a href="#formatcurrency" id="formatcurrency"></a>

Formats the given amount as a currency.

* **`amount`**
* **`setup`** An optional hash array with setup options, with the following possible keys:
  * **`currency`** The currency to format the given amount to. One of the available [`CURRENCY_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants). If not specified, the current [Locale](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale) setting is used.

**Returns:** The formatted amount.

## formatDate( dateTimestamp, setup ) <a href="#formatdate" id="formatdate"></a>

Formats the given date.

* **`dateTimestamp`** The timestamp to use, in UNIX timestamp format. The hours, minutes and seconds are considered irrelevant.
* **`setup`** An optional hash array with setup options, just like the [Locale::formatTimestamp](#formattimestamp) method.

**Returns:** The formatted date.

## formatNumber( number, setup ) <a href="#formatnumber" id="formatnumber"></a>

Formats the given number.

* **`number`**
* **`setup`** An optional hash array with options, with the following possible keys:
  * **`decimals`** The number of decimals to show. Default: `0`
  * **`decimalMark`** The decimal mark to use, either DECIMAL\_MARK\_POINT or DECIMAL\_MARK\_COMMA. Defaults to the current locale setting.
  * **`isSeparateThousands`** Whether to separate thousands or not. Default: `false`
  * **`multiplier`** A multiplier, or false if no multiplier should be applied. Default: `false`

**Returns:** The formatted number.

## formatTimestamp( timestamp, setup ) <a href="#formattimestamp" id="formattimestamp"></a>

Formats the given date/time according to current locale settings.

* **`timestamp`** The timestamp to use, in UNIX timestamp format. Considered to be in the engine's default timezone configured in [Engine::init](https://cherrycake.tin.cat/version-0.x/core-classes/engine/methods#init), except if the `fromTimeZone` is given via `setup`.
* **`setup`** A hash array of setup options with the following possible keys:
  * **`fromTimezone`** Considers the given timestamp to be in this timezone. If not specified, the timestamp is considered to be in the current [Locale](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale) timestamp. Default: `false`.
  * **`toTimezone`** Converts the given timestamp to this timezone. If not specified, the given timestamp is converted to the current [Locale](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale) timestamp except if the `fromTimeZone` setup key has been set to `false`. Default: `false`.
  * **`language`** If specified, this language will be used instead of the detected one. One of the available [`LANGUAGE_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants).
  * **`style`** The formatting style, one of the available [`TIMESTAMP_FORMAT_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants) constants.
  * **`isShortYear`** Whether to abbreviate the year whenever possible. For example: `17` instead of `2017.` Default: `true`
  * **`isDay`** Whether to include the day. Default: `true`
  * **`isHours`** Whether to include hours and minutes. Default: `false`
  * **`hoursFormat`** The format of the hours. One of the available [`HOURS_FORMAT_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants). Default: `HOURS_FORMAT_24`
  * **`isSeconds`** Whether to include seconds. Default: `false`
  * **`isAvoidYearIfCurrent`** Whether to avoid the year if it's the current one. Default: `false`
  * **`isBrief`** Whether to use a brief formatting whenever possible. Default: false.
  * **`format`** If specified this format as used in the date PHP function is used instead of internal formatting. Default: `false`

**Returns:** The formatted timestamp.

## getLanguageCode( language ) <a href="#getlanguagecode" id="getlanguagecode"></a>

Gets the code of a language.

* **`language`** The language, one of the available [`LANGUAGE_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants) constants.

**Returns:** The language code, or `false` if the specified language is not configured.

## getLanguageName( language, setup ) <a href="#getlanguagename" id="getlanguagename"></a>

Gets the name of a language.

* **`language`** The language, one of the available [`LANGUAGE_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants) constants.
* **`setup`** An optional hash array of setup options, with the following possible keys:
  * **`forceLanguage`** Use this language instead of the passed in `language`

**Returns:** The language name, `false` if the specified language is not configured.

## getMainDomain( localeName )

Gets the main domain name for the current locale, or for the specified locale

* **`localeName`** The name of the locale for which to get the main domain

**Returns:** The main domain for the specified locale, or for the current locale if no `locale` specified. `false` if the locale was not found.

## getText( code, setup ) <a href="#gettext" id="gettext"></a>

Gets a text from the multilingual texts database.

* **`code`** The code of the text. Can also be specified in the `<category code>/<text code>` syntax to differentiate texts stored with the same code in different categories.
* **`setup`** An optional hash array of setup options, with the following possible keys:
  * **`variables`** A hash array of the variables that must be replaced taking the text as a pattern. Every occurrence of `{<key>}` will be replaced with the matching value, where the value can be a string, or a hash array of values for different languages, where each key is one of the available [`LANGUAGE_?`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#constants) constants.
  * **`forceLanguage`** Force the retrieval of the text on this language. If not specified, the detected language is used.
  * **`forceTextCacheTtl`** Use this TTL for the text cache instead of the module configuration variable `textCacheDefaultTtl`.
  * **`isPurifyVariables`** Whether to purify values from specified variables for security purposes or not. Defaults to `true`.

**Returns:** The text.

## setLocale( localeName )

Sets the locale to use

* **`localeName`** The name of the locale to use, as specified in the [`availableLocales`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#configuration) config key.

**Returns:** `true` if the locale could be set, `false` if the locale wasn't configured in the [`availableLocales`](https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/..#configuration) config key.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cherrycake.tin.cat/version-0.x/reference/core-modules/locale/locale-methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.