Parse an Accept-Language header into ordered locale preferences

Each language range may carry a quality value, entries with equal weights must retain their original order, and malformed tags should be rejected before they affect content negotiation. This parser converts one header value into a predictable list of locale preferences. It normalizes familiar language, script, and region casing, preserves wildcards, validates quality syntax, and returns the result in descending preference order for routing, testing, logging, or application-level locale selection.

Turn the header into an explicit preference list

An Accept-Language header expresses several choices in a small amount of text. A browser might send a regional locale first, a broader language second, and a wildcard as a final fallback. Reading that value directly inside routing code encourages repeated string handling and inconsistent edge cases. This parser produces a preferences array in which every record has a locale and a numeric quality value. Entries without an explicit quality parameter receive the standard value of 1. The list is sorted from highest to lowest quality, while entries with equal quality remain in the same order in which the sender supplied them. That stable behavior matters because position is the only remaining preference signal when weights match. Common casing is normalized for clearer downstream comparisons: languages are lowercase, two-letter regions are uppercase, and four-letter scripts use title case. The wildcard remains an asterisk so an application can recognize a general fallback without treating it as a specific locale.

Reject ambiguous or malformed input early

Header parsing sits at a trust boundary because the value normally comes from a client. Silent recovery can turn a typo into an unexpected language choice, so the parser rejects malformed input instead of guessing what the sender intended. A language range must begin with an alphabetic subtag and may continue with hyphen-separated alphanumeric subtags. Underscores, spaces inside a tag, empty subtags, and punctuation are invalid. The only wildcard accepted is the complete range represented by an asterisk. A quality parameter must use q followed by a value from 0 through 1, with no more than three decimal places; values above 1, negative values, unknown parameters, and repeated semicolons cause an error. Empty comma-separated entries are also rejected. The input is capped at the declared header length to keep processing bounded. These rules make failures visible at the API boundary and prevent a partially parsed header from quietly selecting content that the client did not actually request.

Apply the parsed result to locale negotiation

The ordered output is designed to be a clean input for your own locale matching policy. Walk through the preferences and compare each locale with the translations your application supports. You may try an exact regional match first, then fall back from a locale such as fr-CA to its base language, and finally use the wildcard or your product default. The parser deliberately does not choose that policy for you: supported locales, regional fallback rules, and the treatment of quality zero depend on the application. Keeping parsing separate from selection makes the behavior easier to test and reuse across gateways, server-rendered pages, APIs, and analytics pipelines. It also helps when diagnosing reports that a visitor received the wrong language, because logs can store the structured preference list rather than an opaque raw header. For automated workloads, each request costs $0.002. The browser version runs the same deterministic parsing logic locally, which is useful for inspecting headers during development without sending their contents elsewhere.