BBizKit

locale.equal

v0.1.0 latest

Compare two BCP 47 locale tags for equality per RFC 5646 §2.1.1 case-insensitivity rules.

localecomparisonbcp47i18nequality

Compare two BCP 47 locale tags for equality per RFC 5646 §2.1.1 case-insensitivity rules.

Signature

function equal(a: string, b: string, opt?: EqualOptions): boolean

Type Definitions:

Problem

Locale tags from different sources use different separators and casing (en-US vs en_us vs EN_US). Direct string comparison fails even when two tags are semantically identical, causing cache misses and incorrect conditional branches.

How It Works

Normalizes both tags to lowercase with hyphens, then compares. Always case-insensitive as mandated by BCP 47 / RFC 5646 §2.1.1. Empty subtags from duplicate separators are removed when cleanup is enabled (default).

Boundaries

  • Returns false if either tag is empty or whitespace-only.
  • Throws TypeError for non-string input.
  • Does not perform alias resolution (e.g. 'iw' and 'he' are not equal).
  • Does not add or strip likely subtags.

Replaces

Common boilerplate this function replaces:

a.toLowerCase().replace(/_/g, '-') === b.toLowerCase().replace(/_/g, '-')

Examples

locale.equal("en-US", "en_us");  // true
locale.equal("zh-Hant-TW", "ZH-HANT-TW");  // true
locale.equal("en", "en-US");  // false
locale.equal("", "en");  // false
locale.equal("  en-US  ", "en-US");  // true

Standards

Caveats

  • Comparison is purely syntactic — no semantic equivalence (e.g. alias resolution).
  • Whitespace-only inputs return false, not TypeError.

FAQ

How to compare two locale tags that might be formatted differently?

Use locale.equal(a, b) which normalizes separators and casing before comparison, so 'zh_TW' and 'zh-tw' are considered equal.

Is locale comparison case-sensitive?

No. locale.equal() is always case-insensitive, as mandated by BCP 47 / RFC 5646 §2.1.1.

Does locale.equal handle underscores?

Yes. Underscores are treated as equivalent to hyphens by default via the acceptSeparators option.

How to check if two locale tags are the same locale?

locale.equal('en-US', 'en_us') returns true. It normalizes separators and casing before comparison.

Does locale.equal resolve locale aliases?

No. 'iw' and 'he' are not considered equal. Only syntactic normalization is performed.

Referenced Standards