From 4881acb7b3a9aacd64b0f00f3b85fd736aa53316 Mon Sep 17 00:00:00 2001 From: Christian Kaisermann Date: Tue, 21 Jan 2020 10:59:26 -0300 Subject: [PATCH] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20make=20getClientLocale?= =?UTF-8?q?=20tree-shakeable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BREAKING CHANGE: It's now needed to explicitly import the `getClientLocale` method to use its heuristics when setting the initial locale. This makes the method and its helpers to be tree-shakeable. ```js import { init, getClientLocale } from 'svelte-i18n' init({ initialLocale: getClientLocale({ ... }) }) ``` --- docs/Getting Started.md | 6 +-- docs/Methods.md | 74 +++++++++++++++++++----------- src/runtime/configs.ts | 7 +-- src/runtime/index.ts | 1 + test/runtime/configs.test.ts | 19 -------- test/runtime/stores/locale.test.ts | 13 +++--- 6 files changed, 59 insertions(+), 61 deletions(-) diff --git a/docs/Getting Started.md b/docs/Getting Started.md index e9a0740..16719c4 100644 --- a/docs/Getting Started.md +++ b/docs/Getting Started.md @@ -64,7 +64,7 @@ After populating your [`$dictionary`](/docs/Dictionary.md) with [`addMessages()` ```js // src/i18n.js -import { register, init } from 'svelte-i18n' +import { register, init, getClientLocale } from 'svelte-i18n' register('en', () => import('./en.json')) register('en-US', () => import('./en-US.json')) @@ -73,9 +73,9 @@ register('pt', () => import('./pt.json')) init({ fallbackLocale: 'en', - initialLocale: { + initialLocale: getClientLocale({ navigator: true, // i.e 'en-US' - }, + }), }) // starts loading 'en-US' and 'en' ``` diff --git a/docs/Methods.md b/docs/Methods.md index fbec8c8..b9c53fd 100644 --- a/docs/Methods.md +++ b/docs/Methods.md @@ -10,46 +10,24 @@ Method responsible for configuring some of the library behaviours such as the gl interface InitOptions { // the global fallback locale fallbackLocale: string - // set of heuristic configs to define the client's locale - initialLocale?: InitialLocaleOptions + // the app initial locale + initialLocale?: string // custom time/date/number formats formats?: Formats // loading delay interval loadingDelay?: number } - -interface InitialLocaleOptions { - // the fallback locale to use if no message is found in the current one - fallback?: string - // when 'true', check the 'window.navigator.language' to set the current locale - navigator?: boolean - // key to look for a locale on 'window.location.search' - // 'example.com?locale=en-US' - search?: string - // key to look for a locale on 'window.location.hash' - // 'example.com#locale=en-US' - hash?: string - // pattern to look in the window.location.pathname. - // It returns the first capturing group. - pathname?: RegExp - // pattern to look in the window.location.hostname. - // It returns the first capturing group. - hostname?: RegExp -} ``` **Example**: ```js -import { init } from 'svelte-i18n' +import { init, getClientLocale } from 'svelte-i18n' init({ // fallback to en if current locale is not in the dictionary fallbackLocale: 'en', - initialLocale: { - // based on the user's browser - navigator: true, - }, + initialLocale: 'pt-br', }) ``` @@ -90,6 +68,50 @@ init({ ``` +#### getClientLocale + +> `import { getClientLocale } from 'svelte-i18n'` + +`getClientLocale(options: GetClientLocaleOptions): void` + +Optional utility method to help getting the initial locale of a user. Use it together with the [`init()`](#init) method. + +```ts +interface GetClientLocaleOptions { + // the fallback locale to use if no message is found in the current one + fallback?: string + // when 'true', check the 'window.navigator.language' to set the current locale + navigator?: boolean + // key to look for a locale on 'window.location.search' + // 'example.com?locale=en-US' + search?: string + // key to look for a locale on 'window.location.hash' + // 'example.com#locale=en-US' + hash?: string + // pattern to look in the window.location.pathname. + // It returns the first capturing group. + pathname?: RegExp + // pattern to look in the window.location.hostname. + // It returns the first capturing group. + hostname?: RegExp +} +``` + +**Example**: + +```js +import { init, getClientLocale } from 'svelte-i18n' + +init({ + // fallback to en if current locale is not in the dictionary + fallbackLocale: 'en', + initialLocale: getClientLocale({ + // based on the user's browser + navigator: true, + }), +}) +``` + #### addMessages `import { addMessages } from 'svelte-i18n` diff --git a/src/runtime/configs.ts b/src/runtime/configs.ts index a3603f7..853eda6 100644 --- a/src/runtime/configs.ts +++ b/src/runtime/configs.ts @@ -1,4 +1,3 @@ -import { getClientLocale } from './includes/getClientLocale' import { ConfigureOptions } from './types' import { $locale } from './stores/locale' @@ -63,11 +62,7 @@ export function getOptions() { export function init(opts: ConfigureOptions) { const { formats, ...rest } = opts - const initialLocale = opts.initialLocale - ? typeof opts.initialLocale === 'string' - ? opts.initialLocale - : getClientLocale(opts.initialLocale) || opts.fallbackLocale - : opts.fallbackLocale + const initialLocale = opts.initialLocale || opts.fallbackLocale Object.assign(options, rest, { initialLocale }) diff --git a/src/runtime/index.ts b/src/runtime/index.ts index a521f02..295fb24 100644 --- a/src/runtime/index.ts +++ b/src/runtime/index.ts @@ -13,6 +13,7 @@ export function waitLocale(locale?: string) { } export { init } from './configs' +export { getClientLocale } from './includes/getClientLocale' export { $locale as locale } from './stores/locale' diff --git a/test/runtime/configs.test.ts b/test/runtime/configs.test.ts index af8c896..bc56923 100644 --- a/test/runtime/configs.test.ts +++ b/test/runtime/configs.test.ts @@ -29,25 +29,6 @@ test('inits the initial locale by string', () => { expect(get($locale)).toBe('en') }) -test('inits the initial locale by client heuristics', () => { - delete window.location - window.location = { - search: '?lang=en-US&foo', - pathname: '/', - hostname: 'example.com', - hash: '', - } as any - - init({ - fallbackLocale: 'pt', - initialLocale: { - search: 'lang', - }, - }) - expect(getOptions().initialLocale).toBe('en-US') - expect(get($locale)).toBe('en-US') -}) - test('adds custom formats for time, date and number values', () => { const customFormats = require('../fixtures/formats.json') diff --git a/test/runtime/stores/locale.test.ts b/test/runtime/stores/locale.test.ts index dbf9f97..90c40cc 100644 --- a/test/runtime/stores/locale.test.ts +++ b/test/runtime/stores/locale.test.ts @@ -8,10 +8,11 @@ import { getCurrentLocale, $locale, isRelatedLocale, -} from '../../../src/runtime/stores/locale' -import { getOptions, init } from '../../../src/runtime/configs' -import { register } from '../../../src/runtime' -import { hasLocaleQueue } from '../../../src/runtime/includes/loaderQueue' +} from '../../../src/client/stores/locale' +import { getOptions, init } from '../../../src/client/configs' +import { register } from '../../../src/client' +import { hasLocaleQueue } from '../../../src/client/includes/loaderQueue' +import { getClientLocale } from '../../../src/client/includes/getClientLocale' beforeEach(() => { init({ fallbackLocale: undefined }) @@ -113,9 +114,7 @@ test('if no initial locale is set, set the locale to the fallback', () => { test('if no initial locale was found, set to the fallback locale', () => { init({ fallbackLocale: 'en', - initialLocale: { - hash: 'lang', - }, + initialLocale: null, }) expect(get($locale)).toBe('en') expect(getOptions().fallbackLocale).toBe('en')