International Standard Code Application Skill

When implementing phone number, country code, and region code related components, you must follow the standards below. For the detailed guide, refer to code-standard-reference.md in this directory.

Application Targets

Automatically applied when writing/modifying files that meet the following conditions:

• •File name contains phone, tel, country, region, address, locale, i18n, intl
• •Code contains logic related to phone number input, country selection, or region/address selection
• •Code handles country codes (alpha-2/alpha-3), region codes (ISO 3166-2), or international phone number data

Reference Data Files

Core Rules

1. Use ISO 3166-1 alpha-2 codes for country identification

• •Use 2-character uppercase alpha-2 codes for all fields that identify a country (e.g., KR, US, JP)
• •Store as codes, not full name strings — display names are looked up from iso_3166_1_countries.json
• •Use alpha-3 when 3-character codes are needed (e.g., KOR, USA, JPN)

// Good
interface Address {
  countryCode: string;  // ISO 3166-1 alpha-2 (e.g., "KR")
  regionCode: string;   // ISO 3166-2 (e.g., "KR-11")
}

// Bad
interface Address {
  country: string;  // "South Korea" — direct string storage prohibited
}

2. Use ISO 3166-2 codes for regions/administrative divisions

• •Use ISO 3166-2 codes for fields that identify a region (e.g., KR-11, US-CA)
• •Code format: {alpha-2}-{subdivision} (country code + hyphen + subdivision code)
• •Region lists are filtered from iso_3166_2_regions.json based on the selected country

3. Phone numbers must follow E.164 format

• •International phone number format: +{country code}{number} (e.g., +821012345678)
• •Country codes are looked up from country_calling_codes.json
• •Input UI should separate country selection and number input
• •Store in full E.164 format when saving

// Good: Separate country code and number input, store as E.164
const phoneNumber = `${callingCode}${localNumber.replace(/[^0-9]/g, '')}`;
// e.g., "+82" + "1012345678" → "+821012345678"

// Bad: Free-form text input
const phone = userInput; // Format not guaranteed

4. Country/region selection UI data should be constructed from standard JSON files

Country selection dropdown:

• •Construct list from iso_3166_1_countries.json
• •Display: Korean name or English name (depending on locale)
• •Value: alpha-2 code
• •Place major countries at the top (Korea, USA, Japan, China, etc.)

Region selection dropdown:

• •Filter administrative regions for the selected country from iso_3166_2_regions.json
• •Display: local name (nameLocal) or English name (nameEn)
• •Value: ISO 3166-2 code (e.g., KR-11)
• •Update region list in conjunction with country selection

Phone number country code selector:

• •Construct list from country_calling_codes.json
• •Display: flag + country name + calling code (e.g., 🇰🇷 South Korea +82)
• •Value: callingCode (e.g., +82)
• •Store alpha-2 code alongside for country identification

5. Data model field rules

6. Language-specific implementation patterns

TypeScript/React

// Country selection component data type
interface Country {
  koreanName: string;
  englishName: string;
  alpha2: string;      // Used as value
  alpha3: string;
  numeric: string;
}

// Region selection data type
interface Region {
  code: string;        // ISO 3166-2 code (e.g., "KR-11")
  nameEn: string;
  nameLocal?: string;
  type: string;
}

// Phone number input data type
interface CallingCode {
  countryNameKo: string;
  alpha2: string;
  callingCode: string;  // e.g., "+82"
}

Java/Spring

// Country code field
@Column(name = "NATN_CD", length = 2, columnDefinition = "CHAR(2)")
private String nationCode;  // ISO 3166-1 alpha-2

// Region code field
@Column(name = "RGN_CD", length = 6)
private String regionCode;  // ISO 3166-2 (e.g., "KR-11")

// International phone number field
@Column(name = "INTL_TELNO", length = 15)
private String internationalPhoneNumber;  // E.164 format

Python/Django

# Country code field
nation_code = models.CharField(
    max_length=2, verbose_name="Country Code"
)  # ISO 3166-1 alpha-2

# Region code field
region_code = models.CharField(
    max_length=6, verbose_name="Region Code"
)  # ISO 3166-2

# International phone number field
intl_phone_number = models.CharField(
    max_length=15, verbose_name="International Phone Number"
)  # E.164 format