{"_id":"@arc-laboratories/arclocale-locales","name":"@arc-laboratories/arclocale-locales","dist-tags":{"alpha":"0.1.0-alpha.3","latest":"0.1.0-alpha.3"},"versions":{"0.1.0-alpha.3":{"name":"@arc-laboratories/arclocale-locales","version":"0.1.0-alpha.3","description":"ArcLocale locales","private":false,"repository":{"type":"git","url":"git+https://github.com/Arc-Laboratories/arclocale.git","directory":"packages/locales"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"type":"module","sideEffects":false,"main":"build/index.cjs","module":"build/index.mjs","types":"build/index.d.ts","keywords":[],"author":"","license":"Apache-2.0","devDependencies":{"@types/node":"22.13.5","tsup":"8.5.1","typescript":"5.9.3","vitest":"4.1.4"},"dependencies":{"iso-639-3":"3.0.1"},"scripts":{"dev":"tsup --watch","build":"pnpm typecheck && tsup","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest"},"_id":"@arc-laboratories/arclocale-locales@0.1.0-alpha.3","bugs":{"url":"https://github.com/Arc-Laboratories/arclocale/issues"},"homepage":"https://github.com/Arc-Laboratories/arclocale#readme","_integrity":"sha512-5C1Xk0845+YYtY7nVAlINtGp/wKg/jSZ75Mtg7eklyT+N/oeW1cl768zJVwEOhvvPZcQOkR33qoM9HvZtu8yOA==","_resolved":"/private/var/folders/vq/lk2vwfg5753bswtmgzzgl0dw0000gn/T/6059c8c6350d3e9ca803473396caec30/arc-laboratories-arclocale-locales-0.1.0-alpha.3.tgz","_from":"file:arc-laboratories-arclocale-locales-0.1.0-alpha.3.tgz","_nodeVersion":"22.15.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-5C1Xk0845+YYtY7nVAlINtGp/wKg/jSZ75Mtg7eklyT+N/oeW1cl768zJVwEOhvvPZcQOkR33qoM9HvZtu8yOA==","shasum":"13c44b0399957cc327749f92c7355136e40aa07a","tarball":"https://registry.npmjs.org/@arc-laboratories/arclocale-locales/-/arclocale-locales-0.1.0-alpha.3.tgz","fileCount":6,"unpackedSize":1611610,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE7OyVNiJPEgyt96Fn5omcs7A6gpsbeVnS8scOdXa4OfAiEAgOkX1VudUXLjHj4BWF/15FFWWkLWtnMjlsQf+p54iyU="}]},"_npmUser":{"name":"mzaza","email":"mzazakeith@gmail.com"},"directories":{},"maintainers":[{"name":"mzaza","email":"mzazakeith@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/arclocale-locales_0.1.0-alpha.3_1779736903879_0.8045222953983175"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T19:21:43.631Z","0.1.0-alpha.3":"2026-05-25T19:21:44.084Z","modified":"2026-05-25T19:21:44.349Z"},"maintainers":[{"name":"mzaza","email":"mzazakeith@gmail.com"}],"description":"ArcLocale locales","homepage":"https://github.com/Arc-Laboratories/arclocale#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/Arc-Laboratories/arclocale.git","directory":"packages/locales"},"bugs":{"url":"https://github.com/Arc-Laboratories/arclocale/issues"},"license":"Apache-2.0","readme":"# @arc-laboratories/arclocale-locales\n\nA JavaScript package that helps developers work with locale codes (like \"en-US\" or \"zh-Hans-CN\") and get country/language names in different languages.\n\n## Features\n\n- **Locale Parsing**: Break apart locale strings into language, script, and region components\n- **Validation**: Check if locale codes are properly formatted and use real ISO codes\n- **Name Resolution**: Get localized names for countries, languages, and scripts in 200+ languages\n- **Small Bundle Size**: Core package is ~12KB with on-demand data loading\n- **Full TypeScript Support**: Complete type definitions included\n\n## Installation\n\n```bash\nnpm install @arc-laboratories/arclocale-locales\n```\n\n## Usage\n\n### Locale Parsing\n\n```typescript\nimport {\n  parseLocale,\n  getLanguageCode,\n  getScriptCode,\n  getRegionCode,\n} from \"@arc-laboratories/arclocale-locales\";\n\n// Parse complete locale\nparseLocale(\"en-US\"); // { language: \"en\", region: \"US\" }\nparseLocale(\"zh-Hans-CN\"); // { language: \"zh\", script: \"Hans\", region: \"CN\" }\nparseLocale(\"sr-Cyrl-RS\"); // { language: \"sr\", script: \"Cyrl\", region: \"RS\" }\n\n// Extract individual components\ngetLanguageCode(\"en-US\"); // \"en\"\ngetScriptCode(\"zh-Hans-CN\"); // \"Hans\"\ngetRegionCode(\"en-US\"); // \"US\"\n```\n\n### Validation\n\n```typescript\nimport {\n  isValidLocale,\n  isValidLanguageCode,\n  isValidScriptCode,\n  isValidRegionCode,\n} from \"@arc-laboratories/arclocale-locales\";\n\n// Validate complete locales\nisValidLocale(\"en-US\"); // true\nisValidLocale(\"en-FAKE\"); // false\nisValidLocale(\"xyz-US\"); // false\n\n// Validate individual components\nisValidLanguageCode(\"en\"); // true\nisValidLanguageCode(\"xyz\"); // false\nisValidScriptCode(\"Hans\"); // true\nisValidScriptCode(\"Fake\"); // false\nisValidRegionCode(\"US\"); // true\nisValidRegionCode(\"ZZ\"); // false\n```\n\n### Name Resolution (Async)\n\n```typescript\nimport {\n  getCountryName,\n  getLanguageName,\n  getScriptName,\n} from \"@arc-laboratories/arclocale-locales\";\n\n// Get country names in different languages\nawait getCountryName(\"US\"); // \"United States\"\nawait getCountryName(\"US\", \"es\"); // \"Estados Unidos\"\nawait getCountryName(\"CN\", \"fr\"); // \"Chine\"\n\n// Get language names in different languages\nawait getLanguageName(\"en\"); // \"English\"\nawait getLanguageName(\"en\", \"es\"); // \"inglés\"\nawait getLanguageName(\"zh\", \"fr\"); // \"chinois\"\n\n// Get script names in different languages\nawait getScriptName(\"Hans\"); // \"Simplified Han\"\nawait getScriptName(\"Hans\", \"es\"); // \"han simplificado\"\nawait getScriptName(\"Latn\", \"zh\"); // \"拉丁文\"\n```\n\n## API Reference\n\n### Parsing Functions\n\n#### `parseLocale(locale: string): LocaleComponents`\n\nBreaks apart a locale string into its components.\n\n**Parameters:**\n\n- `locale` (string): The locale string to parse\n\n**Returns:** `LocaleComponents` object with `language`, `script`, and `region` properties\n\n**Examples:**\n\n```typescript\nparseLocale(\"en-US\"); // { language: \"en\", region: \"US\" }\nparseLocale(\"zh-Hans-CN\"); // { language: \"zh\", script: \"Hans\", region: \"CN\" }\nparseLocale(\"es\"); // { language: \"es\" }\n```\n\n#### `getLanguageCode(locale: string): string`\n\nExtracts just the language part from a locale string.\n\n#### `getScriptCode(locale: string): string | null`\n\nExtracts the script part from a locale string.\n\n#### `getRegionCode(locale: string): string | null`\n\nExtracts the region/country part from a locale string.\n\n### Validation Functions\n\n#### `isValidLocale(locale: string): boolean`\n\nChecks if a locale string is properly formatted and uses real codes.\n\n#### `isValidLanguageCode(code: string): boolean`\n\nChecks if a language code is valid (ISO 639-1).\n\n#### `isValidScriptCode(code: string): boolean`\n\nChecks if a script code is valid (ISO 15924).\n\n#### `isValidRegionCode(code: string): boolean`\n\nChecks if a region code is valid (ISO 3166-1 alpha-2 or UN M.49).\n\n### Name Resolution Functions\n\n#### `getCountryName(countryCode: string, displayLanguage = \"en\"): Promise<string>`\n\nGets a country name in the specified language.\n\n**Parameters:**\n\n- `countryCode` (string): The country code (e.g., \"US\", \"CN\")\n- `displayLanguage` (string, optional): The language to display the name in (default: \"en\")\n\n**Returns:** Promise<string> - The localized country name\n\n#### `getLanguageName(languageCode: string, displayLanguage = \"en\"): Promise<string>`\n\nGets a language name in the specified language.\n\n#### `getScriptName(scriptCode: string, displayLanguage = \"en\"): Promise<string>`\n\nGets a script name in the specified language.\n\n## Supported Formats\n\nThe package supports both hyphen (`-`) and underscore (`_`) delimiters:\n\n- `en-US` or `en_US` → `{ language: \"en\", region: \"US\" }`\n- `zh-Hans-CN` or `zh_Hans_CN` → `{ language: \"zh\", script: \"Hans\", region: \"CN\" }`\n\n## Data Sources\n\n- **Locale parsing**: Uses regex-based parsing with ISO standard validation\n- **Name resolution**: Uses Unicode CLDR (Common Locale Data Repository) data\n- **Validation**: Uses official ISO 639-1, ISO 15924, and ISO 3166-1 standards\n\n## Performance\n\n- **Bundle size**: Core package is ~12KB (ESM) / ~14KB (CJS)\n- **Runtime data**: Loaded on-demand from GitHub raw URLs\n- **Caching**: In-memory cache to avoid repeated network requests\n- **Fallback**: Graceful degradation to English when language data is unavailable\n\n## Error Handling\n\nAll functions include comprehensive error handling:\n\n```typescript\ntry {\n  parseLocale(\"invalid\");\n} catch (error) {\n  console.log(error.message); // \"Invalid locale format: invalid\"\n}\n\ntry {\n  await getCountryName(\"XX\");\n} catch (error) {\n  console.log(error.message); // \"Country code \"XX\" not found\"\n}\n```\n\n## TypeScript Support\n\nFull TypeScript support with comprehensive type definitions:\n\n```typescript\ninterface LocaleComponents {\n  language: string;\n  script?: string;\n  region?: string;\n}\n\ntype LocaleDelimiter = \"-\" | \"_\";\n\ninterface ParseResult {\n  components: LocaleComponents;\n  delimiter: LocaleDelimiter | null;\n  isValid: boolean;\n  error?: string;\n}\n```\n\n## License\n\nApache 2.0\n","readmeFilename":"README.md","_rev":"1-7585025c668cb0139a3bd86a3b23da04"}