NSLocale

Written by Mattt Thompson on

Internationalization is like flossing: everyone knows they should do it, but probably don't.

And like any habit, it becomes second-nature with practice, to the point that you couldn't imagine not doing it. All it takes is for someone to show you the way.

Let NSHipster be your dental hygienist Virgil through these foreign lands.. without all of the lecturing about tooth decay (promsies!)

i18n versus l10n

As is necessary in any discussion about Internationalization (i18n) or Localization (l10n), we must take some time to differentiate the two:

  • Localization is the process of adapting your application for a specific market, or locale.
  • Internationalization is the process of preparing your app to be localized.

Internationalization is a necessary, but not sufficient condition for localization, and will be the focus of this article. Localization, which involves the translation of text and assets into a particular language, will be covered in a future edition of NSHipster.

What makes internationalization difficult is having to think outside of your cultural context. All of the assumptions you have about the way things are supposed to work must be acknowledged and reconsidered. You have to fight the urge to write off things that may seem trivial, like sorting and collation, and empathize with the pain and confusion even minor differences may cause.

Fortunately for us, we don't have to do this alone. Meet NSLocale:

NSLocale

NSLocale is a Foundation class that encapsulates all of the conventions about language and culture for a particular locale. A locale encompasses all of the linguistic and cultural norms of a particular group of people, including:

  • Language
  • Keyboards
  • Number, Date, and Time Formats
  • Currency
  • Collation and Sorting
  • Use of Symbols, Colors, and Iconography

Each locale corresponds to a locale identifier, such as en_US, fr_FR, ja_JP, and en_GB, which include a language code (e.g. en for English) and a region code (e.g. US for United States).

Locale identifiers can encode more explicit preferences about currency, calendar system, or number formats, such as in the case of de_DE@collation=phonebook,currency=DDM, which specifies German spoken in Germany, using phonebook collation, and using the pre-Euro Deutsche Mark.

Users can change their locale settings in the "Language & Text" (or "International" on older versions of OS X) System Preferences on the Mac, or "General > International" in iOS Settings.

Language & Text System Preferences

Formatting Dates & Numbers

Although NSLocale encapsulates a rich set of domain-specific information, its typical usage is rather understated.

If there's just one thing you should learn about NSLocale, it's that you should always pass [NSLocale currentLocale] into your NSDateFormatter and NSNumberFormatter instances. Doing this will ensure that dates, numbers, and currencies will be formatted according to the localization preferences of the user.

Actually, make that a meta lesson about locales: always use NSDateFormatter and NSNumberFormatter when displaying anything to do with dates or numbers, respectively.

But let's get back to some of the cool features of NSLocale itself, shall we?

-objectForKey:

NSLocale typifies Foundation's obsession with domain-specific pedantry, and nowhere is this more visible than in -objectForKey:. Cue the list of available constants:

  • NSLocaleIdentifier
  • NSLocaleLanguageCode
  • NSLocaleCountryCode
  • NSLocaleScriptCode
  • NSLocaleVariantCode
  • NSLocaleExemplarCharacterSet
  • NSLocaleCalendar
  • NSLocaleCollationIdentifier
  • NSLocaleUsesMetricSystem
  • NSLocaleMeasurementSystem
  • NSLocaleDecimalSeparator
  • NSLocaleGroupingSeparator
  • NSLocaleCurrencySymbol
  • NSLocaleCurrencyCode
  • NSLocaleCollatorIdentifier
  • NSLocaleQuotationBeginDelimiterKey
  • NSLocaleQuotationEndDelimiterKey
  • NSLocaleAlternateQuotationBeginDelimiterKey
  • NSLocaleAlternateQuotationEndDelimiterKey

While this all may seem like fairly esoteric stuff, you may be surprised by the number of opportunities your application has to use this information to make for a better user experience.

It's the small things, like knowing that quotation marks vary between locales:

  • English: “I can eat glass, it doesn't harm me.”
  • German: „Ich kann Glas essen, das tut mir nicht weh.“
  • Japanese:「私はガラスを食べられます。それは私を傷つけません。」

So if you were building a component that added quotations around arbitrary text, you should use NSLocaleQuotationBeginDelimiterKey and NSLocaleAlternateQuotationEndDelimiterKey rather than assuming @"\"" for English quotation marks.

-displayNameForKey:value:

Another impressive, albeit mostly-useless method is -displayNameForKey:value:, which can return the display name of a locale identifier (NSLocaleIdentifier):

let locale = NSLocale(localeIdentifier: "fr_FR")

let fr_FR = locale.displayNameForKey(NSLocaleIdentifier, value: "fr_FR")
let en_US = locale.displayNameForKey(NSLocaleIdentifier, value: "en_US")
NSLocale *frLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];
NSLog(@"fr_FR: %@", [frLocale displayNameForKey:NSLocaleIdentifier value:@"fr_FR"]);
NSLog(@"en_US: %@", [frLocale displayNameForKey:NSLocaleIdentifier value:@"en_US"]);
  • fr_FR: "français (France)"
  • en_US: "anglais (États-Unis)"

You should use this method any time you need to display information about the user's current locale, or any alternative locales available to them, like in this screen from the Settings app:

Languages Settings

+preferredLanguages

One final method worth mentioning is NSLocale +preferredLanguages, which returns an array of IETF BCP 47 language identifier strings, in order of user preference.

An app that communicates with a web server can use these values to define the Accept-Language HTTP header, such that the server has the option to return localized resources:

// Accept-Language HTTP Header; see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
let acceptLanguage: String = {
    var components: [String] = []
    for (index, languageCode) in enumerate(NSLocale.preferredLanguages() as [String]) {
        let q = 1.0 - (Double(index) * 0.1)
        components.append("\(languageCode);q=\(q)")
        if q <= 0.5 {
            break
        }
    }

    return join(",", components)
}()

let URL = NSURL(string: "http://nshipster.com")
var mutableRequest = NSMutableURLRequest(URL: URL)

mutableRequest.setValue(acceptLanguage, forHTTPHeaderField: "Accept-Language")
NSMutableURLRequest *request = ...;
[request setValue:[NSString stringWithFormat:@"%@", [[NSLocale preferredLanguages] componentsJoinedByString:@", "]], forHTTPHeaderField:@"Accept-Language"];

Even if your server doesn't yet localize its resources, putting this in place now will allow you to flip the switch when the time comes, without having to push an update to the client. Neat!


Internationalization is often considered to be an un-sexy topic in programming--just another chore that most projects don't have to worry about. In actuality, designing software for other locales is a valuable exercise (and not just for the economic benefits of expanding your software into other markets).

One of the greatest joys and challenges in programming is in designing systems that can withstand change. The only way designs can survive this level of change is to identify and refactor assumptions about the system that may not always hold. In this way, internationalization represents the greatest challenge, making us question everything about our cultural identity. And in doing so, we become not just better programmers, but better people, too.

So go and be a better person: make NSLocale part of your daily ritual.

Follow NSHipster
Recommended Reading
NSHipster: Obscure Topics in Cocoa & Objective-C
19.99

NSHipster

Obscure Topics in Cocoa & Objective-C

Combining articles from NSHipster.com with new essays, this book is the essential guide for modern iOS and OS X developers.

Buy Now on Gumroad
Next Article

Accessibility, like internationalization, is one of those topics that's difficult to get developers excited about. But as you know, NSHipster is all about getting developers excited about this kind of stuff.