• This filter should be configured with the type URL

  • v3 API reference


The language detection filter is only included in contrib images


The language detection filter is experimental and is currently under active development.


The language detection filter does not work on Windows (the blocker is getting icu compiled).

The language detection filter (i18n) picks the best match between the desired locales of a client and an application’s supported locales and adds a new x-language header to the request containing an IETF BCP 47 language tag.

The filter parses a list of locales from an Accept-Language header RFC 2616 Section 14.4 to match the desired locale of a client.

Unicode ICU is used for Accept-Language header parsing.

supported_languages: [en, fr]
# Multiple types, weighted with the quality value syntax:
Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, *;q=0.5
  • The client is from the Romandy region and prefers Swiss French, the variety of French spoken in the French-speaking area of Switzerland

  • The client sends an Accept-Language header

  • An Accept-Language header indicates the natural language and locale that the client prefers

  • The application is only configured to match French fr

  • The filter sets the value of the x-language header to fr

x-language: fr

When the filter can not match the desired locale of a client using the supported_languages option, the default_language option will be used as a fallback. The x-language header value will never be empty.

Example configuration

Full filter configuration:

name: envoy.filters.http.language
  default_language: en
  supported_languages: [en, en-uk, de, dk, es, fr, zh, zh-tw]

The above configuration can be understood as follows:

  • Try to pick the client’s desired locale from an Accept-Language header

  • At any point the filter uses Unicode ICU for locale parsing

  • If the client’s desired locale can not be picked, for example because the client provided an invalid value, the default_language option will be used as a fallback


The language detection filter outputs statistics in the http.<stat_prefix>.language. namespace. The stat prefix comes from the owning HTTP connection manager.






Number of requests for which the language from the Accept-Language header (RFC 2616 Section 14.4) was matched



Number of requests for which the default language was used (fallback)