pyVideoTrans

Appearance

As a developer, have you ever been overwhelmed by this bewildering array of codes?

  • In a user registration form, is the country list using CN or CHN?
  • For multilingual translation (i18n), should the folder be named zh or zh-CN?
  • When handling video subtitles, a spec demands an unfamiliar three-letter code—sometimes zho, sometimes chi—what's the difference?
  • Not to mention seemingly random time zone identifiers like Asia/Shanghai.

After reading this, you will thoroughly understand the logic behind these codes and be able to confidently use them correctly in your projects.

Core Idea: Divide and Conquer

These standards seem chaotic because we try to understand them with a vague concept of "region." But the principle of the computer world is precision. Therefore, international standards organizations "divide and conquer" the fuzzy concept of "region," breaking it down into several specific, orthogonal (mutually independent) dimensions, and establishing a gold standard for each.

Our journey of exploration begins with understanding these dimensions.

1. Geography: Where Am I? - ISO 3166-1 ​

This is the foundation of all codes, answering the simplest question: "What is this country/region?"

  • Standard Name: ISO 3166-1
  • Core Mission: Provide unique identifiers for countries and regions worldwide.
  • Primary Formats:
    • alpha-2 (Two-letter code): e.g., US, CN, JP. This is the most commonly used and universal format.
    • alpha-3 (Three-letter code): e.g., USA, CHN, JPN. More readable, often used in data statistics and official documents.

Developer Practical Guide: ​

  • Database Design: When storing a country in a user table, create a country_code field, using the CHAR(2) type to store the two-letter code (alpha-2). For example:
sql
CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(255),
    country_code CHAR(2)
);
  • API Design: Region-related APIs (e.g., e-commerce shipping ranges) should use two-letter codes as parameters. For example:
http
GET /api/v1/shipping?country=CN HTTP/1.1
  • Frontend Development: In a country selection dropdown, the value for <option value="CN">China</option> should use the two-letter code. For example:
html
<select name="country">
    <option value="CN">China</option>
    <option value="US">United States</option>
    <option value="JP">Japan</option>
</select>

Learn More ​

2. Language: What Do I Speak? - ISO 639 ​

This standard cares about only one thing: Which language are we using?

  • Standard Name: ISO 639
  • Core Mission: Encode the world's languages.
  • Primary Formats:
    • ISO 639-1 (Two-letter code): e.g., en, zh, ja. It covers about 184 major world languages, conventionally in lowercase.
    • ISO 639-2 (Three-letter code, T and B categories): e.g., eng, zho, jpn. It covers over 500 languages, addressing the limited coverage of two-letter codes.
    • ISO 639-3 (Three-letter code): e.g., eng, zho, jpn. ISO 639-3 is an extension of ISO 639-2, aiming to be a superset covering all individual languages.

Learn More ​

3. Precise Localization: Where Am I and What Do I Speak? - Locale ​

Now, we combine the first two to answer a more precise question: "What specific language is the user using in a specific region?" This is the concept of Locale.

  • Standard Name: No single standard, typically follows the IETF BCP 47 specification, combining ISO 639 and ISO 3166-1.
  • Core Mission: Precisely describe language variants in specific regions to handle differences in spelling, vocabulary, date formats, currency symbols, etc.
  • Format: language-code-COUNTRY-code (language-COUNTRY)
    • en-US: English used in the United States.
    • en-GB: English used in the United Kingdom.
    • zh-CN: Chinese used in Mainland China (specifically Simplified).
    • zh-TW: Chinese used in Taiwan, China (specifically Traditional).

Developer Practical Guide: ​

  • Software Internationalization (i18n): Your resource files (e.g., translation strings) should be placed in folders named by Locale, e.g., values-zh-CN/strings.xml (Android). For example:
res/
    values/
        strings.xml
    values-zh-CN/
        strings.xml
  • HTTP Request Header: Parse the Accept-Language: zh-CN,zh;q=0.9 header to return the most suitable language version for the user. For example:
http
Accept-Language: zh-CN,zh;q=0.9
  • Date/Currency Formatting: Libraries in all modern programming languages accept Locale as a parameter. For example, in Java:
java
Locale locale = new Locale("zh", "CN");
DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.DEFAULT, locale);
String dateStr = dateFormat.format(new Date());

Learn More ​

4. Professional Fields & Special Cases: Subtitles, Multimedia & T/B Codes - ISO 639-2 ​

Why don't video subtitles simply use zh or en? Because professional fields require broader language coverage, and this is also the root of the "one language, multiple codes" problem.

  • Standard Name: ISO 639-2 (Three-letter code)

  • Key Knowledge Point: T/B Codes (Terminology/Bibliographic Codes) About 20+ languages have two three-letter codes in ISO 639-2, stemming from historical reasons:

    • B Code (Bibliographic): Derived from the English name, primarily used for library cataloging, a historical legacy. For example, German -> ger.
    • T Code (Terminology): Derived from the language's native name, recommended for use in modern computer applications. For example, Deutsch -> deu.

    The most common example is Chinese:

    • chi is the B code (from Chinese).
    • zho is the T code (from 中文, Zhōngwén).
LanguageEnglish NameNative NameB Code (Old/Cataloging)T Code (New/Terminology)Recommended Use
ChineseChinese中文chizhozho
GermanGermanDeutschgerdeudeu
FrenchFrenchFrançaisfrefrafra
TibetanTibetanབོད་ཡིགtibbodbod

Developer Practical Guide: ​

  • Golden Rule: Prefer the T code! It is designed for technical applications. However, when dealing with legacy systems or external data, your code needs compatibility, able to recognize both T and B codes.
  • Media Processing: Use the T code with FFmpeg. For example:
bash
ffmpeg -i input.mp4 -metadata:s:s:0 language=zho output.mp4
  • Data Cleaning: When receiving data from external sources, use a mapping function to unify codes. For example, in Python:
python
language_map = {
    "chi": "zho",
    "ger": "deu",
    "fre": "fra",
    "tib": "bod",
}

def normalize_language_code(code):
    return language_map.get(code, code)

5. Ultimate Challenge: Time and Time Zones - IANA Time Zone Database ​

Why can't we use the country code US to represent US time? Because the continental US has 4 time zones, plus complex daylight saving time rules.

  • Standard Name: IANA Time Zone Database (also known as tz database or Olson database)
  • Core Mission: Precisely define the boundaries of all time zones worldwide, their offsets from UTC, and all historical daylight saving time change rules.
  • Format: Continent/Representative_City (Area/Location)
    • Asia/Shanghai
    • America/New_York
    • Europe/London

Developer Practical Guide: ​

  • Golden Rule: Never calculate time zones or daylight saving time yourself!
  • Backend Development: On the server, all times should be stored in UTC, using IANA identifiers when converting to local time. For example, in Java:
java
Instant instant = Instant.now();
String timestamp = instant.toString();
  • Frontend Development: Browser APIs can get the user's time zone. For example, in JavaScript:
javascript
const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

Learn More ​

Quick Reference Cheat Sheet ​

Task ScenarioWhat Do I Need?Use StandardExample CodeKey Developer Point
Select CountryUnique country IDISO 3166-1 alpha-2CN, USDatabase CHAR(2) storage, API param
Webpage or Simple TranslationIdentify a major languageISO 639-1zh, enHTML lang attribute, i18n foundation
Precise LocalizationDistinguish regional language variantsIETF BCP 47zh-CN, en-USi18n folder naming, HTTP header, formatting
Subtitle/Audio Track TaggingCover as many languages as possibleISO 639-2zho (recommended)Prefer T code, be compatible with B code
Handle Local TimePrecisely calculate time & DSTIANA Time Zone DBAsia/ShanghaiServer stores UTC, client uses IANA ID for conversion

Now, the fog has cleared. These codes are not the product of chaos but a well-designed, clearly divided system. Mastering them will enable you to:

  1. Build a Clear Mental Model: Understand the applicable scenarios for each code and the historical reasons behind special cases like zho/chi.
  2. Write More Robust Code: Gracefully handle global user needs while maintaining compatibility with legacy data.
  3. Collaborate Efficiently: Communicate with your team using precise terminology.