Getting the User’s Locale

You can obtain the user’s locale using either the currentLocale or autoupdatingCurrentLocale class methods in the NSLocale class.

If you use the currentLocale method, the property values of the returned object are guaranteed not to change. Therefore, use the currentLocale method if you want to perform operations that need to be consistent.

If you use the autoupdatingCurrentLocale method, the property values can change when the user changes the region settings. However, you are not notified if the returned object changes.

To observe locale preference changes, read Registering for Locale and Time Zone Changes.

Getting Information About a Locale

Use the objectForKey: instance method in the NSLocale class to access information about a locale. For example, pass the NSLocaleUsesMetricSystem key to this method to get a Boolean number that determines whether the locale uses the metric system:

NSNumber *metricSystem = [[NSLocale currentLocale] objectForKey:NSLocaleUsesMetricSystem];

Pass the NSLocaleCurrencySymbol key to get a string representation of the locale’s currency symbol:

NSString *currencySymbol = [[NSLocale currentLocale] objectForKey:NSLocaleCurrencySymbol];

For a complete list of locale property keys, see NSLocale Component Keys.

Getting Localized Language and Dialect Names

The identifiers that specify languages and dialects in APIs and folder names—for example, de-CH, en-AU, and pt-PT—shouldn’t be displayed to users. To get a human-readable, localized language or dialect name, use the displayNameForKey:value: method in the NSLocale class, passing NSLocaleIdentifier as the key parameter.

To get the localized name for languages and dialects

1. Get the language that the app is using.

   NSString *languageID = [[NSBundle mainBundle] preferredLocalizations].firstObject;

   The returned string is a language ID that identifies a written language or dialect, as described in Language and Locale IDs.

2. Get the associated locale object.

   NSLocale *locale = [NSLocale localeWithLocaleIdentifier:languageID];

   If you pass the language ID as the locale ID parameter, a locale for the language is returned. For example, if you pass de-CH as the language, the Switzerland locale is returned.

3. Get the localized language name.

   NSString *localizedString = [locale displayNameForKey:NSLocaleIdentifier value:languageID];

The format of the string is [Language] ([Dialect]). For example, if the language ID is de-CH, the localized language string is “Deutsch (Schweiz).” If the language ID is de, the localized language string is “Deutsch.”

Getting Language-Specific Quotes

Beginning and ending quotes, which vary in different languages, can be obtained from the locale object. Use the same technique, described in Getting Localized Language and Dialect Names, to obtain the default locale for the language, and then use the locale component keys to obtain the language-specific quotes.

To create a string that uses locale-sensitive quotes

1. Get the language that the app is using.

   NSString *languageID = [[NSBundle mainBundle] preferredLocalizations].firstObject;

2. Get the associated locale object.

   NSLocale *locale = [NSLocale localeWithLocaleIdentifier:languageID];

3. Get the beginning and ending symbols for quotes from the locale object.

   bQuote = [locale objectForKey:NSLocaleQuotationBeginDelimiterKey];

   eQuote = [locale objectForKey:NSLocaleQuotationEndDelimiterKey];

4. Format a string using the locale-sensitive quotes.

   quotedString = [NSString stringWithFormat:@"%@%@%@", bQuote, myText, eQuote];

Table 4-2 shows the results when myText is “@iPhone”for different regions.

Creating Formatted Strings

At a minimum, use the localizedStringWithFormat: method in the NSString class, not the stringWithFormat: method to format user-facing text. A simple fix to existing code is to replace occurrences of the stringWithFormat: method with the alternate localizedStringWithFormat: method throughout your code, as in:

NSString *localizedString = [NSString localizedStringWithFormat:@"%3.2f", myNumber];

This method uses the system locale. To specify the user’s locale preference, pass [NSLocale currentLocale] as the locale parameter to either the initWithFormat:locale: or initWithFormat:locale:arguments: method. For best results, use data-specific formatter objects and preset styles, described in Formatting Dates and Times and Formatting Numbers.

Changing the Case of Strings

The process of changing the case in strings is not the same for all languages. Use these locale-sensitive NSString methods to change the case:

• uppercaseStringWithLocale:

• lowercaseStringWithLocale:

• capitalizedStringWithLocale:

If you pass nil as the locale parameter, the system locale is used, which is incorrect. To specify the user’s locale preference, pass [NSLocale currentLocale] as the locale parameter.

Using Preset Date and Time Styles

To obtain a localized string representation of a date and time using a preset style, use the localizedStringFromDate:dateStyle:timeStyle: class method in the NSDateFormatter class:

NSString *localizedDateTime = [NSDateFormatter localizedStringFromDate:[NSDate date] dateStyle:NSDateFormatterMediumStyle timeStyle:NSDateFormatterShortStyle];

For example, specify a medium style to abbreviate text—such as “Jun 10, 2013”—by passing NSDateFormatterMediumStyle as the style parameter. Specify a short style for numerical only representations—such as “6/10/13” or “11:03 AM”—by passing NSDateFormatterShortStyle as the style parameter. Table 4-3 shows the results of using preset formats when English is the language and United States is the region.

Table 4-4 shows the results of passing NSDateFormatterMediumStyle for the date style and NSDateFormatterShortStyle for the time style for different languages and regions.

Using Custom Date and Time Styles

Use custom date and time styles only when the preset styles don’t meet your needs. However, convert your custom format to a locale-sensitive format before getting string representations of the date and time. The dateFormatFromTemplate:options:locale: class method in the NSDateFormatter class rearranges the given template to adhere to the specified locale.

To get a localized string representation of a date and time using a custom style

1. Create an NSDateFormatter object.

   NSDateFormatter *dateFormatter = [NSDateFormatter new];

2. Use the dateFormatFromTemplate:options:locale: class method to get a localized format string from a template that you provide.

   NSString *localeFormatString = [NSDateFormatter dateFormatFromTemplate:@"dMMM" options:0 locale:dateFormatter.locale];

   The template parameter of the dateFormatFromTemplate:options:locale: method should adhere to Unicode Technical Standard #35, described in Use Format Strings to Specify Custom Formats. For example, the template @”dMMM” specifies that the day of the month and abbreviation for the month should be in the format string. The order of the symbols and any non-symbol characters in the template are ignored.

3. Set the format of the NSDateFormatter instance to the locale-sensitive format string.

   dateFormatter.dateFormat = localeFormatString;

4. Use the stringFromDate: method to get a localized string representation of the date.

   NSString *localizedString = [dateFormatter stringFromDate:[NSDate date]];

For example, if you don’t convert the @“MMM d” string to a locale-sensitive format, the results are not localized, as shown in the second column in Table 4-5.

Parsing Localized Date Strings

The user enters dates using localized formats, so parse input strings accordingly. Use an NSDateFormatter object to convert a localized string to a date object. Set the date formatter’s style using one of the preset styles. (Use a template format string only if a preset style doesn’t work.) Also, allow the date formatter to use heuristics when parsing the string.

To convert a localized date string to a date object

1. Create a date formatter object.

   NSDateFormatter *dateFormatter = [NSDateFormatter new];

2. Set the formatter’s style to a preset style.

   dateFormatter.dateStyle = NSDateFormatterMediumStyle;

   Replace NSDateFormatterMediumStyle with the style you expect the user to enter.

3. If the input string is not expected to contain a time, set the time style to none.

   dateFormatter.timeStyle = NSDateFormatterNoStyle;

4. Set the leniency to YES (enables the heuristics).

   dateFormatter.lenient = YES];

5. Convert the string to a date object.

   NSDate *date = [dateFormatter dateFromString:inputString];

For example, if the locale is United States, the input string is 9/3/14, and the preset style is NSDateFormatterShortStyle, the date is interpreted as 2014-09-03 07:00:00 +0000. However, if the locale is Germany, the date becomes 2014-03-09 08:00:00 +0000.

Using Preset Number Styles

To obtain a localized string representation of a number using a preset style, use the localizedStringFromNumber:numberStyle: class method in the NSNumberFormatter class:

NSString *localizedString = [NSNumberFormatter localizedStringFromNumber:myNumber numberStyle:NSNumberFormatterDecimalStyle];

Table 4-6 lists the preset styles available and compares United States preset formats to other regions.

Parsing Localized Number Strings

The user may enter numbers using localized formats, so parse these input strings accordingly. Use an NSNumberFormatter object to convert a string to a number object. Set the number formatter’s style using one of the preset styles. Also, allow the number formatter to use heuristics when parsing the string.

To convert a localized number string to a number object

1. Create a number formatter object.

   NSNumberFormatter *numberFormatter = [NSNumberFormatter new];

2. Set the formatter’s style to a preset style.

   numberFormatter.numberStyle = NSNumberFormatterDecimalStyle;

   Replace NSNumberFormatterDecimalStyle with the style you expect the user to enter.

3. Set the leniency to YES (enables the heuristics).

   numberFormatter.lenient = YES;

4. Convert the string to a number object.

   NSNumber *number = [numberFormatter numberFromString:inputString];