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
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.
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.
ISO 639-1 Code
ISO 639-2 Code
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.
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.
ISO 3166-1 Code
For a complete list of ISO 3166-1 codes, see Online Browsing Platform (OBP) for ISO country codes.
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.
Language ID syntax
Specifies a language only.
Specifies a dialect of a language.
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.
Script language ID
Azerbaijani in the Arabic script.
Azerbaijani in the Cyrillic script.
Azerbaijani in the Latin script.
Serbian in the Cyrillic script.
Serbian in the Latin script.
Uzbek in the Cyrillic script.
Uzbek in the Latin script.
Chinese in the simplified script.
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.
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
Locale ID syntax
An unspecified region where the language is used.
The language used by and regional preference of the user.
An unspecified region where the script is used.
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 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.