Language and Locale IDs

Language IDs identify a language, dialect, or script and are used to name language-specific resource folders stored in the app bundle. Locale IDs identify a set of regional conventions and are used in APIs—such as the NSLocale, NSDateFormatter, NSNumberFormatter, and NSCalendar classes—where region information is needed to format data. OS X and iOS use standard language ID and locale ID formats that consist of language and region designators. For example, using a language combined with a region designator, a language ID can distinguish between different languages and regional dialects.

Language Designators

A language designator is a code that represents a language. Use the two-letter ISO 639-1 standard (preferred) or the three-letter ISO 639-2 standard. If an ISO 639-1 code is not available for a particular language, use the ISO 639-2 code instead. For example, there is no ISO 639-1 code for the Hawaiian language, so use the ISO 639-2 code. Table B-1 lists language designators for a subset of languages.

Table B-1  Language designator examples

Language

ISO 639-1 Code

ISO 639-2 Code

English

en

eng

French

fr

fre

German

de

ger

Japanese

ja

jpn

Hawaiian

no designator

haw

For a complete list of ISO 639-1 and ISO 639-2 codes, see ISO 639.2 Codes for the Representation of Names and Languages.

Region Designators

A region designator is a code that represents a country. Use the ISO 3166-1 standard, a two-letter, capitalized code shown in Table B-2.

Table B-2  Regional designator examples

Region

ISO 3166-1 Code

United States

US

United Kingdom

GB

Australian

AU

France

FR

Canadian

CA

For a complete list of ISO 3166-1 codes, see Online Browsing Platform (OBP) for ISO country codes.

Language IDs

A language ID identifies a language used in many regions, a dialect used in a specific region, or a script used in multiple regions. To specify a language used in many regions, use a language designator by itself. To specify a specific dialect, use a hyphen to combine a language designator with a region designator. To specify a script, combine a language designator with a script designator. For example, to specify common English, use the en language designator as the language ID. To specify the English language as it is used in the United Kingdom, use en-GB as the language ID.

Table B-3 shows the supported language ID syntax and examples of common languages and dialects.

Table B-3  Language ID syntax and examples

Language ID syntax

Examples

Description

[language designator]

en for English

fr for French

de for German

Specifies a language only.

[language designator]-[region designator]

en-AU for English as used in Australia

en-GB for English as used in United Kingdom

fr-FR for French as used in France

fr-CA for French as used in Canada

de-AT for German as used in Austria

de-CH for German as used in Switzerland

Specifies a dialect of a language.

[language designator]-[script designator]

See Table B-4.

Specifies a script of a language.

For the script designator, use the ISO 15924 standard, four letters with the first letter uppercase and the last three lowercase, as shown in Table B-4.

Table B-4  Script language ID examples

Script language ID

Description

az-Arab

Azerbaijani in the Arabic script.

az-Cyrl

Azerbaijani in the Cyrillic script.

az-Latn

Azerbaijani in the Latin script.

sr-Cyrl

Serbian in the Cyrillic script.

sr-Latn

Serbian in the Latin script.

uz-Cyrl

Uzbek in the Cyrillic script.

uz-Latn

Uzbek in the Latin script.

zh-Hans

Chinese in the simplified script.

zh-Hant

Chinese in the traditional script.

See the “ISO 639-3 and Macro Languages” section of Understanding the New Language Tags for more Chinese language ID examples. For the complete BCP 47 specification for language tags, go to BCP 47: Tags for Identifying Languages. However, iOS and OS X only support the language ID syntax consisting of a language designator and optional region or script designator.

Locale IDs

A locale ID identifies a specific region and its cultural conventions—such as the formatting of dates, times, and numbers. To specify a locale, use an underscore character to combine a language ID with a region designator, as shown in Table B-5. For example, the locale ID for English-language speakers in the United Kingdom is en_GB, while the locale for English-speaking residents of the United States is en_US.

Table B-5  Locale ID syntax and examples

Locale ID syntax

Examples

Description

[language designator]

en

fr

An unspecified region where the language is used.

[language designator]_[region designator]

en_GB

zh_HK

The language used by and regional preference of the user.

[language designator]-[script designator]

az-Arab

zh-Hans

An unspecified region where the script is used.

[language designator]-[script designator]_[region designator]

zh-Hans_HK

The script used by and regional preference of the user.

Only use a script designator in a locale ID when there is ambiguity. For example, because Traditional Chinese is the default language in Hong Kong, use zh_HK, where zh is the code for Traditional Chinese and HK is the code for the Hong Kong region. For Simplified Chinese used in Hong Kong, use zh-Hans_HK as the locale ID, where zh-Hans is the code for the Simplified Chinese script.

Using Subtag Designators

If necessary, you can use a language or locale code that is not known to the NSBundle class or Core Foundation bundle functions. For example, you could create your own language designators for a language that is not yet listed in the ISO conventions or available as a language in Xcode.

If you choose to create a new designator, be sure to follow the rules found in sections 2.2.1 and 4.5 of BCP 47: Tags for Identifying Languages. Tags that do not follow these conventions are not guaranteed to work. When using subtags, ensure that the abbreviation stored by the user’s language settings matches the designator used by your .lproj directory exactly.