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.
Language | ISO 639-1 Code | ISO 639-2 Code |
---|---|---|
English |
|
|
French |
|
|
German |
|
|
Japanese |
|
|
Hawaiian | no designator |
|
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.
Region | ISO 3166-1 Code |
---|---|
United States |
|
United Kingdom |
|
Australian |
|
France |
|
Canadian |
|
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.
Language ID syntax | Examples | Description |
---|---|---|
|
| 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 | Description |
---|---|
| 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.
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
.
Locale ID syntax | Examples | Description |
---|---|---|
|
| 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_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.
Copyright © 2015 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2015-09-16