@lingo.dev/_locales 0.1.0

package/build/index.d.cts

@@ -0,0 +1,266 @@
+/**
+ * Represents the components of a locale string
+ */
+interface LocaleComponents {
+    /** The language code (e.g., "en", "zh", "es") */
+    language: string;
+    /** The script code (e.g., "Hans", "Hant", "Cyrl") - optional */
+    script?: string;
+    /** The region/country code (e.g., "US", "CN", "RS") - optional */
+    region?: string;
+}
+/**
+ * Locale delimiter types
+ */
+type LocaleDelimiter = "-" | "_";
+/**
+ * Validation result for locale parsing
+ */
+interface ParseResult {
+    /** The parsed locale components */
+    components: LocaleComponents;
+    /** The delimiter used in the original string */
+    delimiter: LocaleDelimiter | null;
+    /** Whether the locale string was valid */
+    isValid: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
+
+/**
+ * Shared constants for locale parsing and validation
+ */
+/**
+ * Regular expression for parsing locale strings
+ *
+ * This regex is case-sensitive and expects normalized locale strings:
+ * - Language code: 2-3 lowercase letters (e.g., "en", "zh", "es")
+ * - Script code: 4 letters with preserved case (e.g., "Hans", "hans", "Cyrl")
+ * - Region code: 2-3 uppercase letters or digits (e.g., "US", "CN", "123")
+ *
+ * Matches locale strings in the format: language[-_]script?[-_]region?
+ *
+ * Groups:
+ * 1. Language code (2-3 lowercase letters)
+ * 2. Script code (4 letters, optional)
+ * 3. Region code (2-3 letters or digits, optional)
+ *
+ * Examples:
+ * - "en" -> language: "en"
+ * - "en-US" -> language: "en", region: "US"
+ * - "zh-Hans-CN" -> language: "zh", script: "Hans", region: "CN"
+ * - "sr_Cyrl_RS" -> language: "sr", script: "Cyrl", region: "RS"
+ *
+ * Note: The parser automatically normalizes case before applying this regex:
+ * - Language codes are converted to lowercase
+ * - Script codes preserve their original case
+ * - Region codes are converted to uppercase
+ */
+declare const LOCALE_REGEX: RegExp;
+
+/**
+ * Breaks apart a locale string into its components
+ *
+ * @param locale - The locale string to parse
+ * @returns LocaleComponents object with language, script, and region
+ *
+ * @example
+ * ```typescript
+ * parseLocale("en-US");          // { language: "en", region: "US" }
+ * parseLocale("en_US");          // { language: "en", region: "US" }
+ * parseLocale("zh-Hans-CN");     // { language: "zh", script: "Hans", region: "CN" }
+ * parseLocale("zh_Hans_CN");     // { language: "zh", script: "Hans", region: "CN" }
+ * parseLocale("es");             // { language: "es" }
+ * parseLocale("sr-Cyrl-RS");     // { language: "sr", script: "Cyrl", region: "RS" }
+ * ```
+ */
+declare function parseLocale(locale: string): LocaleComponents;
+/**
+ * Parses a locale string and returns detailed information about the parsing result
+ *
+ * @param locale - The locale string to parse
+ * @returns ParseResult with components, delimiter, and validation info
+ */
+declare function parseLocaleWithDetails(locale: string): ParseResult;
+/**
+ * Extracts just the language code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The language code
+ *
+ * @example
+ * ```typescript
+ * getLanguageCode("en-US");      // "en"
+ * getLanguageCode("zh-Hans-CN"); // "zh"
+ * getLanguageCode("es-MX");      // "es"
+ * getLanguageCode("fr_CA");      // "fr"
+ * ```
+ */
+declare function getLanguageCode(locale: string): string;
+/**
+ * Extracts the script code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The script code or null if not present
+ *
+ * @example
+ * ```typescript
+ * getScriptCode("zh-Hans-CN");   // "Hans"
+ * getScriptCode("zh-Hant-TW");   // "Hant"
+ * getScriptCode("sr-Cyrl-RS");   // "Cyrl"
+ * getScriptCode("en-US");        // null
+ * getScriptCode("es");           // null
+ * ```
+ */
+declare function getScriptCode(locale: string): string | null;
+/**
+ * Extracts the region/country code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The region code or null if not present
+ *
+ * @example
+ * ```typescript
+ * getRegionCode("en-US");        // "US"
+ * getRegionCode("zh-Hans-CN");   // "CN"
+ * getRegionCode("es");           // null
+ * getRegionCode("fr_CA");        // "CA"
+ * ```
+ */
+declare function getRegionCode(locale: string): string | null;
+
+/**
+ * Checks if a locale string is properly formatted and uses real codes
+ *
+ * @param locale - The locale string to validate
+ * @returns true if the locale is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLocale("en-US");        // true
+ * isValidLocale("en_US");        // true
+ * isValidLocale("zh-Hans-CN");   // true
+ * isValidLocale("invalid");      // false
+ * isValidLocale("en-FAKE");      // false
+ * isValidLocale("xyz-US");       // false
+ * ```
+ */
+declare function isValidLocale(locale: string): boolean;
+/**
+ * Checks if a language code is valid
+ *
+ * @param code - The language code to validate
+ * @returns true if the language code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLanguageCode("en");     // true
+ * isValidLanguageCode("zh");     // true
+ * isValidLanguageCode("es");     // true
+ * isValidLanguageCode("xyz");    // false
+ * isValidLanguageCode("fake");   // false
+ * ```
+ */
+declare function isValidLanguageCode(code: string): boolean;
+/**
+ * Checks if a script code is valid
+ *
+ * @param code - The script code to validate
+ * @returns true if the script code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidScriptCode("Hans");     // true (Simplified Chinese)
+ * isValidScriptCode("Hant");     // true (Traditional Chinese)
+ * isValidScriptCode("Latn");     // true (Latin alphabet)
+ * isValidScriptCode("Cyrl");     // true (Cyrillic)
+ * isValidScriptCode("Fake");     // false
+ * ```
+ */
+declare function isValidScriptCode(code: string): boolean;
+/**
+ * Checks if a region/country code is valid
+ *
+ * @param code - The region code to validate
+ * @returns true if the region code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidRegionCode("US");       // true
+ * isValidRegionCode("CN");       // true
+ * isValidRegionCode("GB");       // true
+ * isValidRegionCode("ZZ");       // false
+ * isValidRegionCode("FAKE");     // false
+ * ```
+ */
+declare function isValidRegionCode(code: string): boolean;
+
+/**
+ * Gets a country name in the specified display language
+ *
+ * @param countryCode - The ISO country code (e.g., "US", "CN", "DE")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized country name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getCountryName("US");           // "United States"
+ * await getCountryName("CN");           // "China"
+ *
+ * // Spanish
+ * await getCountryName("US", "es");     // "Estados Unidos"
+ * await getCountryName("CN", "es");     // "China"
+ *
+ * // French
+ * await getCountryName("US", "fr");     // "États-Unis"
+ * ```
+ */
+declare function getCountryName(countryCode: string, displayLanguage?: string): Promise<string>;
+/**
+ * Gets a language name in the specified display language
+ *
+ * @param languageCode - The ISO language code (e.g., "en", "zh", "es")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized language name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getLanguageName("en");          // "English"
+ * await getLanguageName("zh");          // "Chinese"
+ *
+ * // Spanish
+ * await getLanguageName("en", "es");    // "inglés"
+ * await getLanguageName("zh", "es");    // "chino"
+ *
+ * // Chinese
+ * await getLanguageName("en", "zh");    // "英语"
+ * ```
+ */
+declare function getLanguageName(languageCode: string, displayLanguage?: string): Promise<string>;
+/**
+ * Gets a script name in the specified display language
+ *
+ * @param scriptCode - The ISO script code (e.g., "Hans", "Hant", "Latn")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized script name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getScriptName("Hans");          // "Simplified"
+ * await getScriptName("Hant");          // "Traditional"
+ * await getScriptName("Latn");          // "Latin"
+ *
+ * // Spanish
+ * await getScriptName("Hans", "es");    // "simplificado"
+ * await getScriptName("Cyrl", "es");    // "cirílico"
+ *
+ * // Chinese
+ * await getScriptName("Latn", "zh");    // "拉丁文"
+ * ```
+ */
+declare function getScriptName(scriptCode: string, displayLanguage?: string): Promise<string>;
+
+export { LOCALE_REGEX, type LocaleComponents, type LocaleDelimiter, type ParseResult, getCountryName, getLanguageCode, getLanguageName, getRegionCode, getScriptCode, getScriptName, isValidLanguageCode, isValidLocale, isValidRegionCode, isValidScriptCode, parseLocale, parseLocaleWithDetails };

package/build/index.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Represents the components of a locale string
+ */
+interface LocaleComponents {
+    /** The language code (e.g., "en", "zh", "es") */
+    language: string;
+    /** The script code (e.g., "Hans", "Hant", "Cyrl") - optional */
+    script?: string;
+    /** The region/country code (e.g., "US", "CN", "RS") - optional */
+    region?: string;
+}
+/**
+ * Locale delimiter types
+ */
+type LocaleDelimiter = "-" | "_";
+/**
+ * Validation result for locale parsing
+ */
+interface ParseResult {
+    /** The parsed locale components */
+    components: LocaleComponents;
+    /** The delimiter used in the original string */
+    delimiter: LocaleDelimiter | null;
+    /** Whether the locale string was valid */
+    isValid: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
+
+/**
+ * Shared constants for locale parsing and validation
+ */
+/**
+ * Regular expression for parsing locale strings
+ *
+ * This regex is case-sensitive and expects normalized locale strings:
+ * - Language code: 2-3 lowercase letters (e.g., "en", "zh", "es")
+ * - Script code: 4 letters with preserved case (e.g., "Hans", "hans", "Cyrl")
+ * - Region code: 2-3 uppercase letters or digits (e.g., "US", "CN", "123")
+ *
+ * Matches locale strings in the format: language[-_]script?[-_]region?
+ *
+ * Groups:
+ * 1. Language code (2-3 lowercase letters)
+ * 2. Script code (4 letters, optional)
+ * 3. Region code (2-3 letters or digits, optional)
+ *
+ * Examples:
+ * - "en" -> language: "en"
+ * - "en-US" -> language: "en", region: "US"
+ * - "zh-Hans-CN" -> language: "zh", script: "Hans", region: "CN"
+ * - "sr_Cyrl_RS" -> language: "sr", script: "Cyrl", region: "RS"
+ *
+ * Note: The parser automatically normalizes case before applying this regex:
+ * - Language codes are converted to lowercase
+ * - Script codes preserve their original case
+ * - Region codes are converted to uppercase
+ */
+declare const LOCALE_REGEX: RegExp;
+
+/**
+ * Breaks apart a locale string into its components
+ *
+ * @param locale - The locale string to parse
+ * @returns LocaleComponents object with language, script, and region
+ *
+ * @example
+ * ```typescript
+ * parseLocale("en-US");          // { language: "en", region: "US" }
+ * parseLocale("en_US");          // { language: "en", region: "US" }
+ * parseLocale("zh-Hans-CN");     // { language: "zh", script: "Hans", region: "CN" }
+ * parseLocale("zh_Hans_CN");     // { language: "zh", script: "Hans", region: "CN" }
+ * parseLocale("es");             // { language: "es" }
+ * parseLocale("sr-Cyrl-RS");     // { language: "sr", script: "Cyrl", region: "RS" }
+ * ```
+ */
+declare function parseLocale(locale: string): LocaleComponents;
+/**
+ * Parses a locale string and returns detailed information about the parsing result
+ *
+ * @param locale - The locale string to parse
+ * @returns ParseResult with components, delimiter, and validation info
+ */
+declare function parseLocaleWithDetails(locale: string): ParseResult;
+/**
+ * Extracts just the language code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The language code
+ *
+ * @example
+ * ```typescript
+ * getLanguageCode("en-US");      // "en"
+ * getLanguageCode("zh-Hans-CN"); // "zh"
+ * getLanguageCode("es-MX");      // "es"
+ * getLanguageCode("fr_CA");      // "fr"
+ * ```
+ */
+declare function getLanguageCode(locale: string): string;
+/**
+ * Extracts the script code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The script code or null if not present
+ *
+ * @example
+ * ```typescript
+ * getScriptCode("zh-Hans-CN");   // "Hans"
+ * getScriptCode("zh-Hant-TW");   // "Hant"
+ * getScriptCode("sr-Cyrl-RS");   // "Cyrl"
+ * getScriptCode("en-US");        // null
+ * getScriptCode("es");           // null
+ * ```
+ */
+declare function getScriptCode(locale: string): string | null;
+/**
+ * Extracts the region/country code from a locale string
+ *
+ * @param locale - The locale string to parse
+ * @returns The region code or null if not present
+ *
+ * @example
+ * ```typescript
+ * getRegionCode("en-US");        // "US"
+ * getRegionCode("zh-Hans-CN");   // "CN"
+ * getRegionCode("es");           // null
+ * getRegionCode("fr_CA");        // "CA"
+ * ```
+ */
+declare function getRegionCode(locale: string): string | null;
+
+/**
+ * Checks if a locale string is properly formatted and uses real codes
+ *
+ * @param locale - The locale string to validate
+ * @returns true if the locale is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLocale("en-US");        // true
+ * isValidLocale("en_US");        // true
+ * isValidLocale("zh-Hans-CN");   // true
+ * isValidLocale("invalid");      // false
+ * isValidLocale("en-FAKE");      // false
+ * isValidLocale("xyz-US");       // false
+ * ```
+ */
+declare function isValidLocale(locale: string): boolean;
+/**
+ * Checks if a language code is valid
+ *
+ * @param code - The language code to validate
+ * @returns true if the language code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidLanguageCode("en");     // true
+ * isValidLanguageCode("zh");     // true
+ * isValidLanguageCode("es");     // true
+ * isValidLanguageCode("xyz");    // false
+ * isValidLanguageCode("fake");   // false
+ * ```
+ */
+declare function isValidLanguageCode(code: string): boolean;
+/**
+ * Checks if a script code is valid
+ *
+ * @param code - The script code to validate
+ * @returns true if the script code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidScriptCode("Hans");     // true (Simplified Chinese)
+ * isValidScriptCode("Hant");     // true (Traditional Chinese)
+ * isValidScriptCode("Latn");     // true (Latin alphabet)
+ * isValidScriptCode("Cyrl");     // true (Cyrillic)
+ * isValidScriptCode("Fake");     // false
+ * ```
+ */
+declare function isValidScriptCode(code: string): boolean;
+/**
+ * Checks if a region/country code is valid
+ *
+ * @param code - The region code to validate
+ * @returns true if the region code is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidRegionCode("US");       // true
+ * isValidRegionCode("CN");       // true
+ * isValidRegionCode("GB");       // true
+ * isValidRegionCode("ZZ");       // false
+ * isValidRegionCode("FAKE");     // false
+ * ```
+ */
+declare function isValidRegionCode(code: string): boolean;
+
+/**
+ * Gets a country name in the specified display language
+ *
+ * @param countryCode - The ISO country code (e.g., "US", "CN", "DE")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized country name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getCountryName("US");           // "United States"
+ * await getCountryName("CN");           // "China"
+ *
+ * // Spanish
+ * await getCountryName("US", "es");     // "Estados Unidos"
+ * await getCountryName("CN", "es");     // "China"
+ *
+ * // French
+ * await getCountryName("US", "fr");     // "États-Unis"
+ * ```
+ */
+declare function getCountryName(countryCode: string, displayLanguage?: string): Promise<string>;
+/**
+ * Gets a language name in the specified display language
+ *
+ * @param languageCode - The ISO language code (e.g., "en", "zh", "es")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized language name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getLanguageName("en");          // "English"
+ * await getLanguageName("zh");          // "Chinese"
+ *
+ * // Spanish
+ * await getLanguageName("en", "es");    // "inglés"
+ * await getLanguageName("zh", "es");    // "chino"
+ *
+ * // Chinese
+ * await getLanguageName("en", "zh");    // "英语"
+ * ```
+ */
+declare function getLanguageName(languageCode: string, displayLanguage?: string): Promise<string>;
+/**
+ * Gets a script name in the specified display language
+ *
+ * @param scriptCode - The ISO script code (e.g., "Hans", "Hant", "Latn")
+ * @param displayLanguage - The language to display the name in (default: "en")
+ * @returns Promise<string> - The localized script name
+ *
+ * @example
+ * ```typescript
+ * // Default English
+ * await getScriptName("Hans");          // "Simplified"
+ * await getScriptName("Hant");          // "Traditional"
+ * await getScriptName("Latn");          // "Latin"
+ *
+ * // Spanish
+ * await getScriptName("Hans", "es");    // "simplificado"
+ * await getScriptName("Cyrl", "es");    // "cirílico"
+ *
+ * // Chinese
+ * await getScriptName("Latn", "zh");    // "拉丁文"
+ * ```
+ */
+declare function getScriptName(scriptCode: string, displayLanguage?: string): Promise<string>;
+
+export { LOCALE_REGEX, type LocaleComponents, type LocaleDelimiter, type ParseResult, getCountryName, getLanguageCode, getLanguageName, getRegionCode, getScriptCode, getScriptName, isValidLanguageCode, isValidLocale, isValidRegionCode, isValidScriptCode, parseLocale, parseLocaleWithDetails };