How should a multilingual website choose the correct translated page when a browser sends an Accept-Language request header? Treat the header as a language preference, match it against genuinely available translations, return a clearly identified representation using Content-Language where appropriate, and manage caches with Vary when request-header selection influences the response. Provide visible, persistent language controls and reliable fallback routes. HTTP language negotiation is about selecting content; it does not perform the translation itself.
A visitor may ask for French first, accept English second and still land on the wrong version of a product help article because the site ignores preference weights, has no French translation, caches the wrong language variant or redirects every visitor according to location. Readers searching for Accept-Language header examples, HTTP content negotiation, Content-Language response headers, Vary Accept-Language caching, RFC 4647 language matching, multilingual SEO and language fallback need a method grounded in actual user choice rather than browser-detection tricks.
Quick route:
- Read Accept-Language as a preference list, not proof of a person’s identity, location or fluency.
- Use a documented language-matching method and only select translations that exist.
- Identify the response’s intended language audience with Content-Language where useful.
- Use a suitable Vary header and cache-key design when one URL serves header-selected language variants.
- Keep a visible language switcher and stable language-specific URLs where appropriate.
- Test fallbacks, bots, anonymous sessions, shared caches, user overrides and accessibility.
The visible problem: correct translations delivered to the wrong readers
Imagine a parent opening a multilingual educational explanation. The browser prefers Mandarin Chinese, the school links to an English resource, and the service has Chinese and English versions. One system automatically redirects to Chinese based on a network address, another prefers English because of an old cookie, and a third chooses a generic Chinese variant without checking which translation is actually maintained. The content team may have written both versions correctly. Readers nevertheless receive an unpredictable experience.
The problem can be even more confusing when a CDN or shared cache is involved. The first visitor requests an English page and the cache stores it under a URL. The next visitor requests another language but receives the earlier English body because the cache treated both requests as interchangeable. Conversely, a cache keyed on every possible raw Accept-Language value can create excessive variants with little practical value. Reliable multilingual delivery requires a policy connecting available translated resources, HTTP negotiation and cache behaviour.
A third common failure is mistaking negotiation for search-engine language discovery. Google recommends explicit localized page versions and appropriate hreflang relationships where relevant. HTTP Accept-Language preferences, HTML lang, Content-Language and hreflang serve different purposes. Their meanings overlap only partially; setting one of them does not automatically fulfil the others. The best route for a public education resource is often straightforward: users can follow language-specific URLs, and any automatic suggestion remains reversible.
First principles: five different questions hidden behind the word language
What does the user prefer? Accept-Language is a request header through which a user agent may express preferred languages. RFC 9110 describes language ranges, quality weights and a mechanism for a server to consider them. An example such as fr-CA, fr;q=0.8, en;q=0.6 communicates an ordering of acceptable ranges, not three exact instructions that the origin must always obey. The header can be absent, abbreviated, modified or configured by the user.
Which representation was returned? Content-Language describes the intended natural-language audience of a representation. A bilingual learning page can contain both English and Mandarin examples but still be intended primarily for an English-reading audience. The header is not simply a list of every foreign-language word quoted in the page. Similarly, an HTTP field is not a substitute for the language attributes of individual HTML passages.
How was a match chosen? RFC 4647 defines mechanisms including filtering and lookup. A service needs to select a strategy suited to its available language tags, fallback rules and interface. If an application stores fr but receives fr-CA, it may use a documented fallback policy; if the available resource uses a different regional variant, a service should not pretend that every difference is irrelevant. Real translation availability matters.
Why might the cached representation differ? RFC 9110 says Vary identifies request-header fields that influenced representation selection. For a URL whose response really varies by Accept-Language, Vary: Accept-Language can be appropriate, subject to the cache design. It is not a magic instruction that makes translations exist or forces every CDN to serve the intended language. Caches must use compatible selection keys and respect other relevant response controls.
How do search engines discover language alternatives? Google Search Central describes reciprocal hreflang annotations for localized versions when distinct URLs exist. An HTTP preference header is not Google’s multilingual URL map. Nor is a language switcher a replacement for correct alternative relationships. For websites publishing authoritative parallel pages, clear URLs and accurate reciprocal mappings make the structure understandable to users and crawlers.
How can the user change language? The most dependable override is an explicit and accessible control. Browser preferences are hints, and a user’s needs can change by reading task. Someone who speaks Malay may deliberately choose English for a technical examination explanation, while another reader prefers a Mandarin overview. Preserve that choice where appropriate without making it impossible to return to a different language.
A twelve-stage method for selecting and serving translated representations
Stage 1: Inventory actual translated resources
List every resource, its canonical subject, version, URL, locale tag, editorial status and publication date. Distinguish a complete translation from a partial excerpt or machine-generated placeholder. The negotiation layer may only select a page that exists and is suitable for readers.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 2: Define target audiences and fallback
Decide which language varieties and regional differences matter for the site. Write a policy for unavailable variants, including a clear fallback and optional suggestion. Do not promise identical localization quality across language variants when the editorial coverage differs.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 3: Read header preferences correctly
Parse Accept-Language as a structured weighted preference list and handle absent headers, malformed values and wildcards sensibly. Values of q express relative preference; do not treat the raw header string as a content identifier.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 4: Choose a documented matching algorithm
Use an explicit lookup or filtering policy appropriate to the application’s resource catalogue. Determine how region-specific preferences fall back. Keep the matching rules testable rather than hiding them in ad hoc string-prefix comparisons.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 5: Honour explicit reader choice
Give a user-selected language priority in the website experience according to the product’s design, and document how it interacts with other preferences. A browser header should not repeatedly override a language the reader explicitly selected.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 6: Serve a trustworthy language representation
Return the correct text, linked assets, navigation, labels and content metadata for the selected version. Do not return a page labelled French if its principal body remains English.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 7: Set appropriate language indicators
Use a meaningful Content-Language response when appropriate and correct HTML lang and inline language changes within the document. These fields describe different things; check them independently in a response inspector.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 8: Plan URLs and alternate-page metadata
Determine whether each version has a stable language-specific URL, a negotiated shared URL, or a combination. For separately published versions, review reciprocal hreflang mapping and canonical rules following current search guidance.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 9: Configure cache variation
Identify whether the representation varies by Accept-Language, cookie, a URL path or another explicit input. Configure the origin and CDN consistently. Use Vary where selection truly depends on a request field, while avoiding unbounded cache fragmentation.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 10: Check privacy and analytics
Avoid treating the entire preference header as a permanent user profile. Consider minimization, logging practices and genuine user controls. A header can expose a distinctive preference sequence; save only what the service actually needs.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 11: Test error and fallback paths
Exercise unsupported locales, absent language headers, stale translations, crawlers, bots, caches and anonymous sessions. The best fallback preserves access to the information and a visible way to choose a different available language.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Stage 12: Monitor and update safely
Record variant selection results, cache behaviour and broken alternate links after releases. Revalidate when translations change. Human editorial review and technical response inspection should agree about what language was actually delivered.
Write the decision as an observable rule. Include the incoming preference, the list of available versions, the selected URL or body, the language metadata that accompanies it, and the behaviour when the requested language is unavailable. This turns a vague statement such as ‘the site is multilingual’ into a testable service promise.
Before deploying, have an editor verify the actual translation and a developer inspect the HTTP exchange. Neither role should certify the other’s work by assumption. A server can select the correct language tag but serve stale text; a translator can approve a perfect sentence that the public never receives because the cache serves a different version.
Worked examples: twenty-two language negotiation decisions
Each example starts from a visible reader problem and names the distinct layers that should be checked. The header strings are illustrative requests, not real visitor data.
Worked example 1: Canadian French preference
Request or situation: Accept-Language: fr-CA, fr;q=0.8, en;q=0.6 Available context: The site has only fr and en translations.
Method: Use a deliberate matching rule that can consider fr as an available fallback without claiming the page is specifically fr-CA. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Inspect selected URL, Content-Language, visible language control and response cache. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 2: English-only fallback
Request or situation: Accept-Language: ja, ko;q=0.8, en;q=0.5 Available context: Only English is published for this specialised guide.
Method: Serve an honest English fallback with a visible note or language options rather than presenting English text as Japanese. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Verify that readers can still access the resource and no false locale metadata is emitted. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 3: Missing preference header
Request or situation: The request has no Accept-Language field. Available context: An anonymous visitor opens a public education article.
Method: Choose a documented default or language-neutral entry point, not a fabricated profile of the visitor. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Confirm it remains reachable through links and does not redirect endlessly. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 4: User override
Request or situation: The browser prefers German but the reader clicks English. Available context: An explicit choice conflicts with a background preference.
Method: Make the language switcher predictable and do not immediately bounce the user back to German. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Reload and navigate to another page to test persistence as designed. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 5: CDN mixed-language cache
Request or situation: Two visitors share a URL but request French and English. Available context: The CDN caches the first response with an overly broad key.
Method: Use suitable Vary or a different URL architecture with compatible cache keys. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Repeat requests in different orders and compare response content and headers. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 6: Overlong variant key
Request or situation: Many browsers send slightly different preference lists. Available context: The server creates a separate cached copy for each raw header string.
Method: Normalize selection to a small set of available content variants while retaining correct negotiation semantics. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Observe cache hit behaviour and ensure the chosen visible language stays accurate. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 7: Content-Language on a primer
Request or situation: An English-language lesson includes Japanese example sentences. Available context: The page is intended for English-reading students.
Method: Choose language metadata for intended audience, not a naive enumeration of all example text. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Mark actual quoted language passages appropriately in document markup. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 8: Bilingual public notice
Request or situation: One response intentionally speaks to English and Malay readers. Available context: Both full-language statements are part of the same page.
Method: Where appropriate, represent the intended language audiences accurately and keep separate passage markup. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Review that neither language is mistaken for a secondary unverified translation. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 9: Hreflang mismatch
Request or situation: English and Spanish pages exist on distinct URLs. Available context: The team uses only Accept-Language headers and expects search engines to map them automatically.
Method: Add correct alternate-page relationships when appropriate and keep version URLs accessible. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Verify reciprocal annotations and that each page actually contains localized main content. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 10: Regional spelling variant
Request or situation: A site offers en-GB and en-US editorial versions. Available context: A browser prefers en-AU.
Method: Define a transparent fallback instead of assuming the region alone determines a unique version. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Check dates, units, spelling and editorial claims in whichever version is selected. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 11: Cookie preference versus header
Request or situation: The user’s saved language preference conflicts with a new browser profile. Available context: The service must choose which input controls selection.
Method: Document and expose the preference hierarchy so the reader is not trapped. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Test a fresh session, an existing session and an explicit switch. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 12: Search result landing page
Request or situation: Google links directly to the Spanish URL. Available context: An automatic Accept-Language redirect sends an English-preferring browser away.
Method: Preserve access to the linked language-specific page; offer switching instead of unconditionally redirecting. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Check that sharing the URL reproduces the intended content. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 13: API representation
Request or situation: A client requests a localized error description. Available context: The payload contains machine-readable codes and human-readable explanations.
Method: Keep protocol identifiers stable while localizing only appropriate descriptive strings. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Inspect content type, semantic codes, language metadata and fallback. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 14: Machine-generated draft
Request or situation: A translation exists but has not been reviewed. Available context: The site wants to make the locale look available.
Method: Do not advertise an approved translation that does not yet meet the publication policy. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Keep editorial state separate from negotiation configuration. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 15: Shared classroom device
Request or situation: Several students with different language preferences use one tablet. Available context: A saved cookie from the previous student influences the next page.
Method: Provide a visible clear switch and avoid exposing another reader’s personal profile as a language decision. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Test anonymous or guest mode and switching without account leakage. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 16: Unsupported wildcard
Request or situation: Accept-Language contains a wildcard with quality weights. Available context: The service supports a subset of language versions.
Method: Apply the chosen matching rules consistently, including how the wildcard is treated. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Write a fixture recording the winner and the fallbacks for this header. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 17: Stale translation version
Request or situation: French translation is one revision behind English. Available context: The representation is linguistically correct but factually outdated.
Method: Display editorial currency appropriately and do not conceal material differences behind identical navigation. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Review update timelines and source-to-translation synchronization. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 18: Robots and cache
Request or situation: A crawler receives different language content from human browsers at one URL. Available context: The server’s negotiation causes inconsistent discoverability.
Method: Prefer stable accessible language versions and accurate metadata where appropriate. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Test a direct language URL independently of browser preferences. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 19: HTTP 406 policy
Request or situation: A strict client requests an unsupported language. Available context: The site considers returning Not Acceptable.
Method: Assess whether a readable fallback with clear language choices better serves this public resource, consistent with HTTP semantics. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Verify that failure responses do not strand ordinary readers. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 20: Privacy-sensitive language list
Request or situation: A request advertises several uncommon language preferences. Available context: Logging pipelines capture the entire header.
Method: Minimize retention and avoid turning preference data into unnecessary identity inference. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Inspect analytics fields and user preference controls. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 21: Alternate canonical URLs
Request or situation: Localized versions have different language-specific addresses. Available context: The team mistakenly points every language version’s canonical to English.
Method: Design canonical and hreflang metadata consistently with the actual localized pages and search guidance. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Verify page source rather than assuming the SEO plugin output is correct. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Worked example 22: Language switch on error pages
Request or situation: A French user encounters a maintenance error. Available context: Only the normal article template was translated.
Method: Include essential error, safety and recovery instructions in the locale plan. First distinguish a reader preference from an existing translated resource. The request may help select a version, but it neither creates a new translation nor guarantees that the user’s chosen language is available. The returned page must be checked independently for meaning, editorial completeness, navigation and appropriate metadata.
Verification: Test a real server-error path rather than the successful page only. Record the input request, resolved language or URL, response status, selected content language, relevant cache headers, and the result of following the language switcher. Repeat with a second preference and a warm cache. A good test confirms that the user receives usable information, can change language intentionally, and is not caught in a redirect or shared-cache mistake.
Failure modes and repairs
Failure 1: Guessing language from country
Symptom: Geolocation mistakes region for language preference. Repair: Use user selection and available resource metadata instead of assuming residents share one language. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 2: Treating Accept-Language as an absolute command
Symptom: The request asks for a language the site cannot supply. Repair: Apply documented matching and fallback while making the delivered language apparent. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 3: Ignoring quality weights
Symptom: A lower-priority preference wins unpredictably. Repair: Parse priorities and matching rules as structured data, and test the selected outcome. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 4: Using Content-Language as a translation switch
Symptom: The header changes but the body remains untranslated. Repair: Select and verify the real translated representation rather than relabelling English text. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 5: Serving a shared URL without compatible cache selection
Symptom: One user receives another user’s language variant. Repair: Review Vary and all cache keys together; test from cold and warm cache states. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 6: Fragmenting caches by every raw header
Symptom: Performance suffers even when only two languages exist. Repair: Map preferences to available variants and plan caching for those actual resources. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 7: Automatic redirects that override users
Symptom: A direct link to a language page repeatedly redirects away. Repair: Keep explicit language URLs usable and provide a reversible switch. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 8: Confusing hreflang with Content-Language
Symptom: Search engines and browsers lack the appropriate distinct signals. Repair: Implement each metadata mechanism for its actual purpose. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 9: Advertising unpublished translations
Symptom: A partial version appears as a supported locale. Repair: Tie availability to an editorial publication state and an actual reviewed page. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 10: Failing to localize recovery paths
Symptom: Only success pages have translated instructions. Repair: Include error and fallback pages in the localization inventory. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 11: Using language preference as a personal identifier
Symptom: Analytics captures more information than the service needs. Repair: Apply minimization and avoid unnecessary inference about individual identity. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Failure 12: No regression tests after CDN updates
Symptom: Previously reliable selection breaks silently. Repair: Test two or more preference orders against both cached and uncached responses. The acceptance test should say what a person is trying to read and which representation actually reaches that person. A header that looks correct in a log cannot compensate for a stale translation, and a well-translated body does not excuse serving the wrong one. Make both the technical selection and the editorial result inspectable.
Exercises and answer reasoning
For each activity, name the available translated resources, the selected response, the expected headers, the user-control route and one failure you would deliberately test.
Exercise 1: Canadian French preference
Prompt: Accept-Language: fr-CA, fr;q=0.8, en;q=0.6 The site has only fr and en translations. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Use a deliberate matching rule that can consider fr as an available fallback without claiming the page is specifically fr-CA. Inspect selected URL, Content-Language, visible language control and response cache. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 2: English-only fallback
Prompt: Accept-Language: ja, ko;q=0.8, en;q=0.5 Only English is published for this specialised guide. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Serve an honest English fallback with a visible note or language options rather than presenting English text as Japanese. Verify that readers can still access the resource and no false locale metadata is emitted. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 3: Missing preference header
Prompt: The request has no Accept-Language field. An anonymous visitor opens a public education article. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Choose a documented default or language-neutral entry point, not a fabricated profile of the visitor. Confirm it remains reachable through links and does not redirect endlessly. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 4: User override
Prompt: The browser prefers German but the reader clicks English. An explicit choice conflicts with a background preference. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Make the language switcher predictable and do not immediately bounce the user back to German. Reload and navigate to another page to test persistence as designed. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 5: CDN mixed-language cache
Prompt: Two visitors share a URL but request French and English. The CDN caches the first response with an overly broad key. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Use suitable Vary or a different URL architecture with compatible cache keys. Repeat requests in different orders and compare response content and headers. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 6: Overlong variant key
Prompt: Many browsers send slightly different preference lists. The server creates a separate cached copy for each raw header string. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Normalize selection to a small set of available content variants while retaining correct negotiation semantics. Observe cache hit behaviour and ensure the chosen visible language stays accurate. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 7: Content-Language on a primer
Prompt: An English-language lesson includes Japanese example sentences. The page is intended for English-reading students. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Choose language metadata for intended audience, not a naive enumeration of all example text. Mark actual quoted language passages appropriately in document markup. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 8: Bilingual public notice
Prompt: One response intentionally speaks to English and Malay readers. Both full-language statements are part of the same page. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Where appropriate, represent the intended language audiences accurately and keep separate passage markup. Review that neither language is mistaken for a secondary unverified translation. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 9: Hreflang mismatch
Prompt: English and Spanish pages exist on distinct URLs. The team uses only Accept-Language headers and expects search engines to map them automatically. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Add correct alternate-page relationships when appropriate and keep version URLs accessible. Verify reciprocal annotations and that each page actually contains localized main content. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 10: Regional spelling variant
Prompt: A site offers en-GB and en-US editorial versions. A browser prefers en-AU. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Define a transparent fallback instead of assuming the region alone determines a unique version. Check dates, units, spelling and editorial claims in whichever version is selected. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 11: Cookie preference versus header
Prompt: The user’s saved language preference conflicts with a new browser profile. The service must choose which input controls selection. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Document and expose the preference hierarchy so the reader is not trapped. Test a fresh session, an existing session and an explicit switch. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 12: Search result landing page
Prompt: Google links directly to the Spanish URL. An automatic Accept-Language redirect sends an English-preferring browser away. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Preserve access to the linked language-specific page; offer switching instead of unconditionally redirecting. Check that sharing the URL reproduces the intended content. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 13: API representation
Prompt: A client requests a localized error description. The payload contains machine-readable codes and human-readable explanations. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Keep protocol identifiers stable while localizing only appropriate descriptive strings. Inspect content type, semantic codes, language metadata and fallback. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 14: Machine-generated draft
Prompt: A translation exists but has not been reviewed. The site wants to make the locale look available. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Do not advertise an approved translation that does not yet meet the publication policy. Keep editorial state separate from negotiation configuration. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 15: Shared classroom device
Prompt: Several students with different language preferences use one tablet. A saved cookie from the previous student influences the next page. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Provide a visible clear switch and avoid exposing another reader’s personal profile as a language decision. Test anonymous or guest mode and switching without account leakage. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Exercise 16: Unsupported wildcard
Prompt: Accept-Language contains a wildcard with quality weights. The service supports a subset of language versions. Draft the decision your multilingual service should take without inventing a translation that is not available.
Model explanation: Apply the chosen matching rules consistently, including how the wildcard is treated. Write a fixture recording the winner and the fallbacks for this header. A complete answer distinguishes selection from translation, considers the user’s explicit choice, and explains cache and metadata consequences when applicable. The final response should be something a reader can navigate, not simply a technically valid HTTP packet. If you change URL or response policy, rerun the same case with a different preference header to check consistency.
Frequently asked questions
Does Accept-Language translate the page?
No. It is a preference signal that may help a server choose among representations. The translation must already exist. A server should not label an English body as a French resource simply because the browser prefers French.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
What does q=0.8 mean in Accept-Language?
It is a quality weight indicating a relative preference for a language range. Parsing and selection need to follow a documented policy. A missing value conventionally has the default weight specified in HTTP; the result is a preference list, not a personal profile.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
What if the browser sends no Accept-Language?
The service needs a clear default or language-choice entry point. Do not assume a visitor’s identity or language from a missing header. Keep accessible links to language-specific versions and test what anonymous visitors actually see.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Is Content-Language the same as HTML lang?
No. Content-Language describes the intended audience language or languages of a representation, while HTML lang identifies the language of elements and text. Mixed-language pages may need passage-level markup beyond either response header or document-level declaration.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Does Vary: Accept-Language guarantee the cache is correct?
No. Vary signals which request field influenced representation selection, and caches must implement compatible behaviour. A CDN or application can still misconfigure keys or store stale variants. Verify real responses in cold and warm cache conditions.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
When should I use hreflang?
Google documents hreflang for signalling localized page alternatives through HTML, HTTP headers or sitemaps, with specific reciprocal requirements. It addresses search discovery and regional or language alternates, not the same operation as interpreting a browser’s Accept-Language header.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Should my site always redirect users by language?
No. Automatic redirection can disrupt shared links and explicit choices, especially when language is guessed from location. A visible language switcher and stable language-specific URLs are often safer for public educational content.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
What is the difference between lookup and filtering?
RFC 4647 describes language-range matching mechanisms. Lookup chooses one match according to its defined approach; filtering identifies matching sets. Choose a mechanism appropriate to the application and its actual available language tags.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Can English and French live on one page?
Yes. A bilingual page can serve multiple readers. Decide its intended audience accurately, mark passage languages where needed, and test accessibility and navigation. That is different from maintaining distinct full translations on separate URLs.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
How should an API localize errors?
Keep machine-readable status codes and protocol identifiers stable while localizing descriptive messages when the API design supports it. Record fallback behaviour, and ensure clients can distinguish a translation from an invariant technical field.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Why can a user get a stale translation?
The resource catalogue, publication state, URL mapping or cache may be out of sync. Check both the response routing and the content revision; selecting the correct language tag alone does not guarantee that its text is current.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Do language headers create privacy concerns?
A detailed preference list can reveal information about a user. Handle it according to actual operational need; avoid unnecessary logging and identity inference. Browser preferences should be controllable, and a site should respect deliberate reader choices.
For practical use, write a small fixture with the exact request, available variants and resulting response. Then test the same URL after another visitor or session has requested a different language. This demonstrates more than inspecting a single static example: it checks whether the language choice survives the real delivery path.
Sources and contextual next routes
Technical references are RFC 9110: HTTP Semantics for Accept-Language, Content-Language and Vary; RFC 4647: Matching of Language Tags; and Google Search Central on localized versions. These sources describe different facets of selection, language ranges and discoverability; do not treat them as interchangeable mechanisms.
For the language learning side, use the Vocabulary Learning Hub and How English Works. For markup and right-to-left text placement rather than HTTP selection, continue to HTML dir, bdi and RTL text. For multilingual alphabetical lists and discovery, read Unicode CLDR sorting and search. For translating placeholder-based software messages, consult GNU gettext context and plurals.
Final principle: a multilingual service succeeds when the translation actually delivered matches a well-explained selection policy and the reader can change languages confidently. Preferences, labels, URLs, accessibility and caching must agree. A correct language header is a necessary clue in some systems, but the genuine reader outcome is the standard of quality.