Language Codes

Language codes should be formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided here: https://www.w3.org/International/articles/language-tags/. When specifying languages, you can use any language as long as it is a valid BCP 47 code that consists of the language subtag, optional region subtag, and optional script subtag as appropriate.

As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB.

Although script subtags are valid (for example, Chinese can be written in either Traditional or Simplified characters, and you may need to indicate that localizations appear in a specific script), keep in mind that script subtags are for describing text and should not be used for describing audio. For example, you would deliver cmn to describe audio in Mandarin, not cmn-Hant or cmn-Hans.

Note: Although BCP 47 also includes support for UN M.49 region codes in addition to commonly-used alphabetic country codes, the only UN M.49 region code supported by Apple at present is 419 (representing Latin America and the Caribbean). This is useful in forming the language tag es-419 to represent Spanish as used in Latin America (as distinct from Spanish as used in Spain).

Note that while any language code complying with the guidelines above will be accepted, the Apple TV app displays content only in a limited set of languages as shown in the table below. The fourth column of the table is provided for reference only, and may be useful for cross-reference if you have existing data from other sources that uses 3-character ISO 639-3 language codes.

* 419 is a UN M.49 region code. https://unstats.un.org/unsd/methodology/m49/