Locales

The internet is a global network so sites should naturally consider people from different cultures and languages. Socialstack has multiple mechanisms to help your site handle a global audience.

Locales

Locales are the main content type used to describe the available locales on a site. A locale must have at least one language code which is typically based on standard locale codes such as en-GB, en-US or simply en (the default). A Locale can have aliased locale codes as well - this is particularly useful if you turn on the Accept-Language header, where the language codes in this header will be mapped to a locale and your guests will automatically see the site in their preferred language, provided the site has the locale available of course.

Listing Locales

The most basic form of a locale selector is like this:

<Input type='select' contentType='locale' onChange={(e) => {
    // The user selected locale with ID e.target.value
}} />

You can also of course use Loop for more flexibility, or a webRequest('locale/list') for the raw data.

Knowing which locale is in use

The user's selected locale is in the Context (in C#). Because virtually all of the Socialstack API system passes the context around, you'll always be able to quickly grab the locale information:

// context.Locale, context.LocaleId

Over in javascript, the locale is in the frontend equivelant of Context called the Session:

import {useSession} from 'UI/Session';

...

var { session } = useSession();

// session.locale

How the default locale is determined

If a header called Locale is sent to the API, the ID in that header will be set into the Context. Otherwise, the locale ID referenced by the context cookie will be used. If no cookie exists and Accept-Language is active then the initial cookie will gain a locale based on Accept-Language.

Forcing the locale

Based on the above rules, setting a header called Locale forces a particular locale on all requests. To make things more convenient, both webRequest and Form have shortcuts for setting this locale header too. This is the basis of how the admin panel saves to multiple locales as well.

// Get the page list specifically in locale 2.
webRequest('page/list', null, {locale: 2});

<Form .. locale={2}>
</Form>

Switching the in use locale

Because the locale is specified primarily in the serverside context and, by extension, the cookie that the context comes from, you'll need to tell the server if you want to switch locale and it will issue you a new cookie and session. The endpoint that does this is specifically /v1/locale/set/2/, where 2 is the ID of the locale the user wants to switch to. It returns a session so you must either then refresh the page or set it into the session with setSession:

import {useSession} from 'UI/Session';

..

var {session, setSession} = useSession();

var localeId = 2;
webRequest('locale/set/' + localeId).then(response => {

// Update the session:
setSession({...response.json});

// Or, refresh:
// window.location.reload(true);

});

Translating the UI components

See the article on translations on the frontend.