🌍 HintLocale v2.2

Zero-dependency locale detection for browsers and servers. Identifies the user's languages and country using browser signals or HTTP headers — no external APIs, no cookies.

Works with <script>, require(), import — single file, ~28 KB (~9 KB gzipped).

Quick start

Browser

<script src="hint-locale.js"></script>
<script>
  var result = HintLocale.detect();
  console.log(result.topCountry);  // "IL"
  console.log(result.topLanguage); // "he"
</script>

Node.js

const HintLocale = require('./hint-locale.js');

const result = HintLocale.detect({
  languages: ['he-IL', 'en-US'],
  timezone: 'Asia/Jerusalem'
});
// result.topCountry → "IL"  (confidence: 1.0)

ES Modules

import HintLocale from './hint-locale.js';

How scoring works

HintLocale collects three independent signals and weighs them:

| Signal | Source | Points | Why | |---|---|---|---| | Region subtag | navigator.languages (en-US → US) | 40 | Explicit region is the strongest user intent | | Timezone | Intl.DateTimeFormat (Asia/Jerusalem → IL) | 30 | Narrows to a small set of countries | | Cross-bonus | Region + timezone both point to same country | +10 | Two independent signals agreeing = very high confidence | | Language match | Country speaks one of the detected languages | up to 25 | Weighted by language rarity (see below) | | Primary language | User's #1 language = country's primary language | 5 | Tiebreaker signal |

Maximum score: 110 — confidence = score / 110.

Language rarity — solving the "English problem"

English is spoken in 124 countries. Hebrew in 1. If a user's browser reports he, that's a near-certain signal for Israel. If it reports en, it tells us almost nothing.

HintLocale assigns each language a rarity score:

rarity = 1 / (number of countries speaking that language)

| Language | Countries | Rarity | |---|---|---| | Hebrew | 1 | 1.000 | | Japanese | 2 | 0.500 | | German | 11 | 0.091 | | Arabic | 28 | 0.036 | | French | 59 | 0.017 | | English | 124 | 0.008 |

The language-match score is multiplied by this rarity, so rare languages contribute far more to the final score.

Primary vs secondary language

Each country has an ordered language list. The first language is primary (e.g. Hebrew for Israel, French for France). When the user's primary language matches a country's primary language, it gets a bonus. This helps distinguish between France (French primary) and Belgium (French secondary).

Language position decay

The user's language list is also ordered by preference. navigator.languages = ['he', 'en', 'fr'] means Hebrew is #1, English is #2. Later languages contribute progressively less to scoring (divided by 1 + i * 0.4).

API

HintLocale.detect([overrides])

HintLocale.detect({
  languages: ['he-IL', 'en-US'],  // override navigator.languages
  timezone: 'Asia/Jerusalem'       // override Intl timezone
});

Returns:

{
  topCountry: "IL",
  topLanguage: "he",
  timezone: "Asia/Jerusalem",
  languages: [
    { code: "he", name: "עברית", rarity: 1.0, countriesCount: 1 },
    { code: "en", name: "English", rarity: 0.008, countriesCount: 124 }
  ],
  countries: [
    { code: "IL", score: 105.0, confidence: 0.95 },
    { code: "US", score: 40.2,  confidence: 0.37 }
  ],
  signals: {
    navigatorRegions: ["IL", "US"],
    timezoneCountries: ["IL"],
    detectedLanguages: ["he", "en"]
  }
}

HintLocale.getCountry(code)

HintLocale.getCountry("IL");
// { code:"IL", numericCode:376, callingCode:972,
//   languages:["he","ar","en"], primaryLanguage:"he" }

HintLocale.getLanguageName(code)

HintLocale.getLanguageName("he"); // "עברית"

HintLocale.getLanguageRarity(code)

HintLocale.getLanguageRarity("he"); // 1.0 (unique to 1 country)
HintLocale.getLanguageRarity("en"); // 0.008 (124 countries)

HintLocale.countriesForLanguage(code)

Returns array with primary/secondary distinction:

HintLocale.countriesForLanguage("fr");
// [
//   { code: "FR", isPrimary: true },
//   { code: "BE", isPrimary: false },
//   ...
// ]

HintLocale.countriesForTimezone(tz)

HintLocale.countriesForTimezone("Europe/Berlin"); // ["DE"]

HintLocale.parseAcceptLanguage(header)

Parse an HTTP Accept-Language header into a sorted language array:

HintLocale.parseAcceptLanguage("he-IL,he;q=0.9,en-US;q=0.8,en;q=0.7");
// ["he-IL", "he", "en-US", "en"]

HintLocale.fromRequest(req, [extra])

Server-side convenience — reads the Accept-Language header from any HTTP request object:

const result = HintLocale.fromRequest(req, { timezone: "America/Bogota" });
// result.topCountry → "CO"
// result.topLanguage → "he"

Server-side usage

HintLocale works on the server by reading the Accept-Language HTTP header.

Basic — raw Node.js HTTP

const http = require("http");
const HintLocale = require("hint-locale");

http.createServer((req, res) => {
  const locale = HintLocale.fromRequest(req);

  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({
    country: locale.topCountry,    // "IL"
    language: locale.topLanguage,  // "he"
    confidence: locale.countries[0]?.confidence  // 0.85
  }));
}).listen(3000);

That's it. fromRequest reads the Accept-Language header automatically — works with any Node.js HTTP request object (raw http, Express, Koa, Fastify, Hono).

Language-based redirect

const locale = HintLocale.fromRequest(req);
const lang = locale.topLanguage || "en";

res.writeHead(302, { Location: "/" + lang + "/" });
res.end();
// Israeli user → /he/
// Japanese user → /ja/
// Everyone else → /en/

With timezone (higher accuracy)

The timezone isn't in HTTP headers, but you can send it from the client once and pass it as a cookie or query parameter:

<!-- Client-side: send timezone on first visit -->
<script>
  if (!document.cookie.includes("tz=")) {
    var tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
    document.cookie = "tz=" + tz + ";path=/;max-age=31536000";
    location.reload();
  }
</script>

// Server-side: read timezone from cookie and pass it
const cookies = parseCookies(req.headers.cookie); // your cookie parser
const locale = HintLocale.fromRequest(req, { timezone: cookies.tz });

locale.topCountry;   // "CO" (much more accurate with timezone)
locale.topLanguage;  // "he"

Without timezone

Without timezone the library still works — rare languages like Hebrew, Japanese, and Korean still give high confidence. Common languages like English give lower confidence since they're spoken in 124 countries.

const locale = HintLocale.fromRequest(req);
// Accept-Language: he-IL,en;q=0.8
// → topCountry: "IL", confidence: 0.85 (Hebrew is unique to Israel)

// Accept-Language: en
// → topCountry: "US", confidence: 0.22 (English is everywhere — low confidence)

Data format (compact packed strings)

All data is stored as packed strings parsed once on first call:

| Data | Format | Example | |---|---|---| | Countries | CC,numeric,calling,lang1.lang2\|... pipe-delimited | IL,376,972,he.ar.en\|US,840,1,en.es.haw.fr | | Timezones | tz>CC1.CC2;tz>CC3 — inverted index | Asia/Jerusalem>IL;Asia/Tokyo>JP | | Lang names | code:name,code:name | he:עברית,en:English |

This eliminates all string duplication: each timezone string appears once instead of once per country that uses it. First language in each country's list is the primary language.

Use cases

• Auto-select language on first visit without a server round-trip
• Pre-fill country in registration / checkout forms
• Show localized currency before user explicitly chooses
• A/B testing by region — entirely client-side
• Server-side rendering — pass Accept-Language header values as overrides

Browser support

Uses var, no arrow functions, no ES6 built-ins → works in IE11+ and all modern browsers. Timezone detection requires Intl.DateTimeFormat (IE11+ / Chrome 24+ / Firefox 29+ / Safari 10+). Gracefully degrades without timezone.

License

MIT