setLocale
setLocale(locale, scope?) updates the runtime locale and loads the locale payload for that runtime.
It is the supported path for in-page language switching.
ts
1import { initIntl, setLocale } from '@beforesemicolon/intl'2 3initIntl({ locale: 'en-US', srcDir: '/locales' })4await setLocale('fr-FR')Signature
ts
1function setLocale(locale: string, scope?: IntlRuntime): Promise<IntlRuntimeSnapshot>What changes when this runs
- sets runtime locale
- marks runtime status as
loading - loads locale messages (
src/srcDiror custom loader) - loads fallback locale messages when configured
- notifies subscribers with updated snapshot once ready
If locale is unchanged or empty, it resolves immediately with the current snapshot.
ts
1const sameLocale = await setLocale(getIntl().locale) // resolves fast, no fetchScoped vs default runtime
Pass a runtime when language switching should be isolated.
ts
1const preview = createIntl({ locale: 'en-US', srcDir: '/locales/previews' })2await setLocale('ja-JP', preview)Without scope, the package default runtime is changed.
Language switcher pattern
ts
1const localeSelect = document.querySelector('#locale')2 3localeSelect?.addEventListener('change', async (event) => {4 const locale = (event.target as HTMLSelectElement).value5 const snapshot = await setLocale(locale)6 7 document.documentElement.lang = snapshot.locale8 document.documentElement.dir = snapshot.direction9 document.documentElement.classList.remove('is-loading-locale')10})setLocale resolves even if loading fails; check snapshot.status === 'error' before switching UI assumptions.
ts
1const snapshot = await setLocale('ar')2if (snapshot.status === 'error') {3 console.warn(snapshot.error)4}For manual loading without changing active locale, use loadLocale().