tsp-sdk

Getting Started

Install

# using yarn
yarn add tsp-sdk
# using npm
npm install tsp-sdk

Create and Translate

import TSPSDK from 'tsp-sdk';

const translator = new TSPSDK({
  name: 'tsp sdk', // optional, just a identifier
  isSSR: false // optional, true means for server-side rendering
});

translator.create({
  env: 'live', // determine to use live or nonlive api， default live
  locale: 'en', // language code, en, vi, th, zh-Hans etc, case insensitive
  translation: {
    projectId: 1, // optional, project id
    resources: [1], // optional, resource id, it will be ignored when there is a projectId parameter
    collections: [2] // optional, collection id, it will be ignored when there is a projectId parameter
  }
}).then((res) => {
  // res contains translation, assume that the translation data like below
  // resource_1 = {
  //   tsp_test: 'resource 1 test',
  //   tsp_hi: 'hi {0}',
  //   tsp_hello: 'hello {name}',
  // }
  // collection_2 = {
  //   tsp_plural__one: '{count} item',
  //   tsp_plural__other: '{count} items',
  //   tsp_plural1: {
  //     one: '{count} item',
  //     other: '{count} items'
  //   },
  //   tsp_plural2: {
  //     one: '{0} item',
  //     other: '{0} items'
  //   }
  // }
  // then, translation data will be reduced
  // res.translation = {
  //   tsp_test: 'resource 1 test',
  //   tsp_hi: 'hi {0}',
  //   tsp_hello: 'hello {name}',
  //   tsp_plural__one: '{count} item',
  //   tsp_plural__other: '{count} items',
  //   tsp_plural1: {
  //     one: '{count} item',
  //     other: '{count} items'
  //   },
  //   tsp_plural2: {
  //     one: '{0} item',
  //     other: '{0} items'
  //   }
  // }
  // if you just want to get the translation, just return res.translation.

  // translator also provide a $t method, can be used to translate directly.
  translator.$t('tsp_test'); // resource 1 test
  translator.$t('tsp_hi', ['tsp']); // hi tsp
  translator.$t('tsp_hello', { name: 'tsp' }); // hello tsp

  // plural forms, recommend to use this style.
  translator.$t('tsp_plural', 1, { count: 1 }); // 1 item
  translator.$t('tsp_plural', 2, { count: 2 }); // 2 items

  translator.$t('tsp_plural1', 1, { count: 1 }); // 1 item
  translator.$t('tsp_plural1', 2, { count: 2 }); // 2 items
  translator.$t('tsp_plural2', 1, [1]); // 1 item
  translator.$t('tsp_plural2', 2, [2]); // 2 items
});

More create options, please see Here

Switch language

translator.switchLanguage('zh-Hans').then((translation) => {
  // translation = {
  //   tsp_test: '资源 1 测试',
  //   tsp_hi: '嗨 {0}',
  //   tsp_plural1: {
  //     one: '{count} 个',
  //     other: '{count} 个'
  //   },
  //   tsp_plural2: {
  //     one: '{0} 个',
  //     other: '{0} 个'
  //   }
  // }
  // if you just want to get the translation, just return translation.

  translator.$t('tsp_test'); // 资源 1 测试
  translator.$t('tsp_hi', 'tsp'); // 嗨 tsp
  translator.$t('tsp_plural1', 1, { count: 1 }); // 1 个
  translator.$t('tsp_plural1', 2, { count: 2 }); // 2 个
});

Load more translation

translator.loadTranslation({
  resources: [3]
}).then((translation) => {
  // translation = {
  //   tsp_r3: '资源 3'
  // }
  // if you just want to get the translation, just return translation.

  translator.$t('tsp_r3'); // 资源 3
});

loadTranslation supports the second param too. it accepts a language code to specify language

translator.loadTranslation({ resources: [3] }, 'en');

For more details, please see: Here

More Guide

Pluralization

TSP uses CLDR Rules for pluralization, and SDK implements those rules in two forms:

• Use each independent key by adding the __{category} suffix, which category is zero, one, two, few, many, other. Key tsp_plural for example.
• Compose all plural forms into an object, like key tsp_plural1, not recommended

When the SDK can't find the right plural form, it will fall back to using the category one, then other, then use the original key. If all keys can't be found, the SDK will return the key name you pass directly.

For more details, please see: Here

Modularization

If your project has the same key name in 2 resources or collections. you may want to specify the priority on different pages, to do this, you can simply give a name in each translation set. then use switchModule to tell tsp to find translation in this set first.

import TSPSDK from 'tsp-sdk';
// these codes may not work if top-level await is not supported.
// assume that translation data like below
// resource_1 = {
//   greet: 'hello'
// }
// resource_2 = {
//   greet: 'hi'
// }
const translator = new TSPSDK();
await translator.create({
  env: 'live',
  locale: 'en',
  translation: {
    name: 'module1',
    resources: [1]
  }
})
await translator.loadTranslation({
  name: 'module2',
  resources: [2]
});

// will use module1 as current module
translator.$t('greet'); // hello

// now switch to module2
const res = await translator.switchModule('module2');
// switch module will return the translation of that module
// just ignore it if you are using translator of tsp sdk.
// res = {
//   greet: 'hi'
// }
translator.$t('greet'); // hi

or you can just call the switchModule method

const translator = new TSPSDK();
await translator.create({
  env: 'live',
  locale: 'en',
  translation: {
    name: 'module1',
    resources: [1]
  }
})
translator.$t('greet'); // hello
// switch module and load translation
const res = await translator.switchModule({
  name: 'module2',
  resources: [2]
});
translator.$t('greet'); // hi

For more details, please see: Here

the switchLanguage can switch specify translation by given module name as the second param.

translator.switchLanguage('zh-Hans', 'module1');

Merge translation

merge extra translation to the translator in the current locale, if you want to merge to another locale, pass the language code as the second argument.

const data = {
  extra_key: 'Extra Data'
};
translator.mergeTranslation(data);
translator.$t('extra_key'); // Extra Data

Integrate with Vue

import TSPSDK from 'tsp-sdk';
import Vue from 'vue';
import App from './App.vue';

/**
 * for performance reason, we don't set translation data responsive.
 * instead of invoke all component to forceUpdate when language change.
 */
const forceUpdate = (vm) => {
  if (vm.$forceUpdate) {
    vm.$nextTick(() => vm.$forceUpdate())
  }

  if (vm.$children && vm.$children.length) {
    for (let i = 0; i < vm.$children.length; i++) {
      forceUplate(vm.$children[i]);
    }
  }
}

const translator = new TSPSDK();

// append $t method and sdk instance
Vue.prototype.$t = translator.$t.bind(translator);
Vue.prototype.$i18n = translator;

const app = new Vue({
  render(h) => h(App)
});
await translator.create({
  env: 'live',
  locale: 'en',
  translation: {
    name: 'module1',
    resources: [1]
  },
  forceUpdate() {
    forceUpdate(app)
  }
});
// recommend to mount app after translation loaded
app.$mount('#root');

to be continue

API Reference

https://shopee.git-pages.garena.com/seller-fe/tech/tsp/tsp-sdk/classes/tspsdk.html