# Titanium.Locale

> The top level Locale module.

- Source: https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.Locale
- Titanium SDK version: 12.6.4
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 1.5
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy

The `Locale` module works with localization files to which are generated during compilation 
into the operating system specific localization formats. The `Locale` module provides 
locale-specific strings which can be referenced at runtime.  Additionally, the module 
contains a few methods and properties for querying device locale information.

The macro `L` can be used as an alias for the [Titanium.Locale.getString](https://titaniumsdk.com/docs/sdk/Titanium.Locale.md#getString) method.

## Properties

### currentCountry

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Country of the current system locale, as an ISO 2-letter code.

This property holds a value such as `US` or `GB`. See the 
[ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 
country codes section of wikipedia for reference.

### currentLanguage

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Language of the current system locale, as an ISO 2-letter code.

This property holds a value such as `en` or `fr`. See the 
[ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) section of wikipedia for reference.

### currentLocale

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Current system locale, as a combination of ISO 2-letter language and country codes.

This property holds a value such as `en-US` or `en-GB`.
See the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) and 
[ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 
sections of wikipedia for reference.

## Methods

### formatTelephoneNumber

- Platforms: Android

Formats a telephone number according to the current system locale.

Parameters:

- `number` (String): Phone number.

Returns: String

### getCurrencyCode

- Platforms: Android, iPhone, iPad, macOS

Returns the ISO 3-letter currency code for the specified locale.

This method returns one of the ISO 4217 currency codes. For example, 
`getCurrencyCode('en-US')` returns `USD`. See the `xe.com` website 
[Currency List](http://www.xe.com/iso4217.php#section2) section of the `www.xe.com` website for 
reference.

Parameters:

- `locale` (String): Locale, as a combination of ISO 2-letter language and country codes. For example, `en-US` or `en-GB`. See the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) sections of wikipedia for reference.

Returns: String

### getCurrencySymbol

- Platforms: Android, iPhone, iPad, macOS

Returns the currency symbol for the specified currency code.

This method returns one of the international currency symbols. For example, 
`getCurrencySymbol('USD')` returns `$`. See the 
[Currency Symbols](http://www.xe.com/symbols.php#section2) section of the 
`www.xe.com` website for reference.

Parameters:

- `currencyCode` (String): Currency, as an ISO 3-letter code. For example, `USD` or `GBP`. See the [Currency List](http://www.xe.com/iso4217.php#section2) section of the `www.xe.com` website for reference.

Returns: String

### getLocaleCurrencySymbol

- Platforms: Android, iPhone, iPad, macOS

Returns the currency symbol for the specified locale.

This method returns one of the international currency symbols. For example, 
`getLocaleCurrencySymbol('en-US')` returns `$`. See the 
[Currency Symbols](http://www.xe.com/symbols.php#section2) section of the 
`www.xe.com` website for reference.

Parameters:

- `locale` (String): Locale, as a combination of ISO 2-letter language and country codes. For example, `en-US` or `en-GB`. See the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) sections of wikipedia for reference.

Returns: String

### getString

- Platforms: Android, iPhone, iPad, macOS

Returns a string, localized according to the current system locale using the appropriate 
`/i18n/LANG/strings.xml` localization file.

This method is functionaly identical to its alias [Global.L](https://titaniumsdk.com/docs/sdk/Global.md#L). For example, 
`Ti.Locale.getString('thisKey', 'missing key')` produces the same result as 
`L('thisKey', 'missing key')`.

When using with [Global.String.format](https://titaniumsdk.com/docs/sdk/Global.String.md#format) to localize a phrase with multiple string 
substitution placeholders, add the `formatted="false"` directive to the relevant 
`strings.xml` element. See example for a demonstration.

Parameters:

- `key` (String): Key of string.
- `hint` (String, optional): Text to return if key does not exist in the localization file.

Returns: String

Example: String Localization Demonstration

Localize two strings, "hello" and "goodbye" (using the keys "greeting" and "signoff") 
for English and Spanish system locales.  

Note: use the device's system settings to change locales and test this code.

#### `/i18n/en/strings.xml`
``` xml
<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <string name="phrase" formatted="false">You say %2$s and I say %1$s!</string>
  <string name="greeting">hello</string>
  <string name="signoff">goodbye</string>
</resources>
```

#### `/i18n/es/strings.xml`
``` xml
<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <string name="phrase" formatted="false">You say %2$s and I say %1$s!</string>
  <string name="greeting">hola</string>
  <string name="signoff">adios</string>
</resources>
```

#### `/Resources/app.js`
``` js
var i18nMissingMsg = '<no translation available>';

// for English locales, displays "You say goodbye and I say hello!"
// for Spanish locales, displays "You say adios and I say hola!"
Ti.API.info('You say ' + Ti.Locale.getString('signoff', i18nMissingMsg) + ' and I say ' + Ti.Locale.getString('greeting', i18nMissingMsg) + '!');

// uses alias L() instead of Ti.Locale.getString()
// formatted="false" is used in the strings.xml element for multiple string substitution
// for English locales, displays "You say goodbye and I say hello!"
// for Spanish locales, displays "You say adios and I say hola!"
Ti.API.info(String.format(L('phrase'), L('greeting', i18nMissingMsg), L('signoff', i18nMissingMsg)));
```

### parseDecimal

- Platforms: Android, iPhone, iPad, macOS

Parses a number from the given string using the current or given locale.

Parameters:

- `text` (String): The string to be parsed.
- `locale` (String, optional): Locale, as a combination of ISO 2-letter language and country codes. For example, `en-US` or `en-GB`. See the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) sections of wikipedia for reference.

Returns: Number - Returns the parsed number. Returns `NaN` (Not-a-Number) if given string is invalid.

Example: Parsing Localized Numeric Strings

``` javascript
// You can convert to/from a localized numeric string like this.
var numericString = String.formatDecimal(1234.5);
var numericValue = Ti.Locale.parseDecimal(numericString);

// The numbers returned will be the same for the 2 different locales.
var number1 = Ti.Locale.parseDecimal('1,234,567.8', 'en-US');
var number2 = Ti.Locale.parseDecimal('1.234.567,8', 'de-DE');
```

### setLanguage

- Platforms: Android, iPhone, iPad, macOS

Sets the current language of the application.

This property holds a value such as `en` or `fr`. See the 
[ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) section of wikipedia for reference.

On Android you can also specify combination of a ISO 2-letter language and country codes. For example, 
`en-US` or `en-GB`. See the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) and 
[ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 
sections of wikipedia for reference.

When changing to a language with a different layout direction, such as English to Arabic or vice-versa,
you will need to close and re-open the window in order to apply the new right-to-left setting.

Parameters:

- `language` (String): The specified ISO 639-1 code.

## Events

### change

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 7.5.0

Fired when the device locale changes.

On Android, when a listener for this event is not present, by default the application will soft restart
upon a locale change. Once a listener for this event is present, the behaviour for a locale change is developer
defined.

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.