localtor v1.0.3

localtor

JavaScript lib for detecting user's locale by varoius sources (cookies, HTTP, URL, etc.). It does not offer any cookie parser or geo library, it does rather offer a way to combine all data sources, filter out invalid data and to get the best match. It does accept various inputs and it filters invalid data out. Just specify the allowed locals.

Installation

yarn add localtor

npm i localtor -S

Basic Usage

  import localtor from 'localtor';
  
  let locale = '';
  
  locale = localtor({
    locales: ['en', 'de-CH', 'ru-RU', 'fr'],
  }).getLocale([
    'ru',
    'de-CH',
    'en-GB,en;q=0.8,sv',
  ]);
  console.log(locale); //results in 'ru-RU'
  
  locale = localtor({
    locales: ['en', 'de-CH', 'ru-RU', 'fr'],
  }).getLocale([
    false,
    'it-IT',
    ['ar', 'hr'],
    'en-GB,en;q=0.8,sv',
  ]);
  console.log(locale); //results in 'en'

The order is important. The first valid element in the array will be returned. It ignores everything except the defined locales. If you don't define any default locale, then the first entry from options.locales is used as the default value.

Advanced Usage

  import localtor from 'localtor';
  
  let locale = '';

  //get
  locale = localtor({
    default: 'fr',
    locales: ['en', 'de-CH', 'ru-RU', 'fr'],
  }).get([
    ['ru'],
    'de-CH',
    'fr',
  ]);
  console.log(locale);
  /* results in:
  {
    match: 'ru-RU',
    matches: [
      'ru-RU',
      'de-CH',
      'fr',
    ],
  }
  */
  
  //getLocales
  locale = localtor({
    default: 'fr',
    locales: ['en', 'de-CH', 'ru-RU', 'fr'],
  }).getLocales([
    ['ru'],
    'de-CH',
    'fr',
  ]);
  console.log(locale);
  /* results in:
  [
    'ru-RU',
    'de-CH',
    'fr',
  ]
  */
  
  //It's also possible to pass 'named' elements; the names will be preserved and the result
  //would be a normal object instead of an array.
  locale = localtor({
    default: 'fr',
    locales: ['en', 'de-CH', 'ru-RU', 'fr'],
  }).getLocales([
    {pathname: 'ru'},
    {cookie: 'de-CH'},
    {http: 'fr-FR,en;q=0.8,sv'},
  ]);
  console.log(locale);
  /* results in:
  {
    pathname: 'ru-RU',
    cookie: 'de-CH',
    http: 'fr',
  }
  */

Why?

Maximum freedom, easy to use, works well with server-side-rendering (same result). Some real usage example:

server.js:

  const locales = localtor({
    default: config.i18n.default,
    locales: config.i18n.locales,
  }).get([
    {pathname: req.originalUrl.substr(1,5)},
    {cookie: req.cookies.locale},
    {http: req.headers["accept-language"] },
  ]);

Could result in: { match: 'de-CH', matches: { pathname: null, cookie: null, http: 'de-CH' } }

client.js:

  const locale = localtor({
    default: config.i18n.default,
    locales: config.i18n.locales,
  }).getLocale([
    window.location.pathname.substr(1,5),
    Cookies.get('locale'),
  ]);

Could result in: de-CH