Skip to main content
Sets the language Encore serves its copy and offers in. It outranks the browser language on every request the SDK makes. Use it when your app has its own language picker, or when the user’s app language differs from their browser language.
New in the web SDK release that includes language support.

​
Signature

​
Parameters

​
Behavior

  • The SDK keeps the language in the browser’s localStorage until you call clearLanguage(), so it survives page reloads and later configure() calls. Where localStorage is unavailable it falls back to sessionStorage, then to memory for the current page. Encore never stores it on its servers.
  • It is a preference of the browser, not user state, so reset() and logout leave it in place.
  • When the language changes, the SDK drops its cached copy and offers and fetches its configuration again right away. The web SDK does not load offers ahead of time, so they load in the new language on the next show().
  • Setting the language already in effect does nothing.
  • An invalid tag, such as pt_BR or english, is ignored with a console warning, whatever your log level. setLanguage() never throws, and the language already in effect stays.
  • The language is served only when your app has it enabled. Otherwise Encore falls back to the browser languages, then your app’s default language. See Localization.
  • The browser language is still sent as Accept-Language. This call adds the override that outranks it.
  • Call it after configure(). Before configure() the call does nothing, and configure() takes no language.

​
Replaces the language attribute

Setting the language through the language attribute is deprecated, and it is removed at the next major release. It still works: setUserAttributes() and identify() take language out of the attributes, call setLanguage() with it, and log one warning per page load. identify() does this after it has switched to the new user, so copy is fetched again for that user. The language is no longer returned by getUserAttributes(). A language saved through the attribute on an earlier release moves into the override the first time configure() runs, and is removed from the saved attributes. A language you already set with setLanguage() wins, and a saved value that is not a valid tag is dropped. Unlike setLanguage(), the attribute and the carry-over still accept a locale identifier and turn it into a tag, so pt_BR becomes pt-BR and de_DE@currency=EUR becomes de-DE. See the deprecated attribute. A language set through the attribute is stored as the same override, so it also survives reset().

​
Usage

Call it from your app’s own language picker, and call clearLanguage() when the user picks “System default”: