Nostalgic Pickled Mango

    TypeScript icon, indicating that this package has built-in type declarations

    4.2.1 • Public • Published

    Transifex Native is a full end-to-end, cloud-based localization stack for moderns apps.

    Transifex Native SDK: JavaScript i18n

    A general purpose Javascript library for localizing web apps using Transifex Native.

    Requires a Transifex Native Project Token.

    Supported Node.js versions >= 14.x.x

    Related packages:

    Learn more about Transifex Native in the Transifex Developer Hub.

    How it works

    Step1: Create a Transifex Native project in Transifex.

    Step2: Grab credentials.

    Step3: Internationalize the code using the SDK.

    Step4: Push source phrases using the @transifex/cli tool.

    Step5: Translate the app using over-the-air updates.

    No translation files required.


    Upgrade to v2

    If you are upgrading from the 1.x.x version, please read this migration guide, as there are breaking changes in place.

    Quick starting guide

    Install the library using:

    npm install @transifex/native --save


    import { tx, t } from '@transifex/native';
    // initialize
      token: '<PUBLIC PROJECT TOKEN>',
    async function main() {
      // set target language, this will fetch translations Over The Air
      await tx.setCurrentLocale('el');
      // translate something
      const message = t('Welcome {user}', {user: 'Joe'});
      // get supported languages in order to create a language picker
      const languages = await tx.getLanguages();
        name: 'Greek',
        code: 'el',
        localized_name: 'Ελληνικά',
        rtl: false,


    const { tx, t } = require('@transifex/native');
    // initialize
      token: '<PUBLIC PROJECT TOKEN>',


    <script type="text/javascript" src=""></script>
    <script type="text/javascript">
      const tx = Transifex.tx;
      const t = Transifex.t;
      // initialize SDK
        token: '<PUBLIC PROJECT TOKEN>',
      // get all languages
      tx.setCurrentLocale('fr').then(function() {
        // translate something
        const message = t('Welcome {user}', {user: 'Joe'});


    Initialize library

      // Public project token, defaults to empty string
      token: String,
      // CDS endpoint, defaults to
      cdsHost: String,
      // Fetch only strings that contain specific tags from CDS, e.g. "master,react"
      filterTags: String,
      // Missing translation policy, defaults to "new SourceStringPolicy()"
      missingPolicy: Function,
      // Error policy, defaults to "new SourceErrorPolicy()"
      errorPolicy: Function,
      // String renderer, defaults to "new MessageFormatRenderer()"
      stringRenderer: Function,
      // Translation cache, defaults to "new MemoryCache()"
      cache: Function,
      // Optional timeout in milliseconds when fetching languages and
      // strings, defaults to 0 (no-timeout)
      fetchTimeout: Number,
      // Optional interval polling delay in milliseconds while waiting
      // for CDS to warm-up with content, defaults to 250msec
      fetchInterval: Number,


    Fetches list of project languages from CDS, useful for creating a language picker.

    tx.getLanguages(): Promise([
        name: String,
        code: String,
        localized_name: String,
        rtl: Boolean
    // Example
      then(languages => console.log(languages)).
      catch(err => console.log(err))

    Get a list of available locales based on CDS.

    tx.getLocales(): Promise(['code', 'code',...])

    Set current translation language

    Fetches translations from the CDS and stores them in cache. When the promise returns, all content will be translated to that language.

    tx.setCurrentLocale(localeCode): Promise
    // Example
      then(() => console.log('content loaded')).
      catch(err => console.log(err))

    Get current translation language

    Returns the currently selected language code.

    tx.getCurrentLocale(): String(localeCode)
    // Example

    Content translation

    Returns the translation of the passed source string based on the currenly selected language. If the translation is not found, the returned string is handled by the configured missing policy. If an error occurs in the ICU parsing of the string, the error is handled based on the configured error policy.

    The translation is returned unescaped and it is NOT safe to be used inside the HTML document unless escaped

    t(sourceString, params): String(localizedString)
    sourceString: String(ICU syntax string)
    params: Object({
      // optional string context, affects key generation
      _context: String,
      // optional developer comment
      _comment: String,
      // optional character limit instruction for translators
      _charlimit: Number,
      // optional comma separated list of tags
      _tags: String,
      // optional custom key
      _key: String,
      // optionally escape ICU variables
      _escapeVars: Boolean,
      // ICU variables, plurals, gender etc variables...
    // Example
      t('Hello <b>{username}</b>', { username: 'Joe' })
    // "Hello <b>Joe</b>"

    Escaping translations

    Using the translation as is from the t function inside HTML is dangerous for XSS attacks. The translation must be escaped based on two scenarios.

    Escaping text translations

    import { t, escape } from '@transifex/native';
    const translation = escape(t('Hello {username}', { username }));
    // translation is safe to include in HTML

    Escaping HTML source

    HTML source content cannot be globally escaped. In that case, we can just escape the ICU variables using the _escapeVars parameter.

    import { t } from '@transifex/native';
    const html = t('<b>Hello {username}</b>', {
      username: username,
      _escapeVars: true,

    Push source content

    For server side integrations you can also push source content programmatically without using the CLI.

    tx.pushSource(payload, params): Promise
    payload: Object({
      key: {
       string: String,
        meta: {
          context: String,
          developer_comment: String,
          character_limit: Number,
          tags: Array(String),
          occurrences: Array(String),
      key: { .. }
    params: Object({
      // Replace the entire resource content with the pushed content of this request
      purge: Boolean,
      // Replace the existing string tags with the tags of this request
      overrideTags: Boolean,
      // If true, when wait for processing to be complete before
      // resolving this promise
      noWait: Boolean,

    For example:

    const { createNativeInstance } = require('@transifex/native');
    const tx = createNativeInstance({
      token: 'token',
      secret: 'secret',
    await tx.pushSource({
      'mykey': {
        string: 'My string',
        meta: {
          context: 'content', // optional
          developer_comment: 'developer comment', // optional
          character_limit: 10, // optional
          tags: ['tag1', 'tag2'], // optional
          occurrences: ['file.jsx', 'file2.js'], // optional

    Invalidate CDS cache

    Server side integrations can also invalidate the CDS cache programmatically.

      // if true, then purge the cache entirely (not recommended)
      purge: Boolean,
    }): Promise

    For example:

    const { createNativeInstance } = require('@transifex/native');
    const tx = createNativeInstance({
      token: 'token',
      secret: 'secret',
    await tx.invalidateCDS();


    Library for listening to various async events.

    // listen to event
    onEvent(type, function)
    // stop listening event
    offEvent(type, function)
    // trigger an event
    sendEvent(type, payload, caller)

    Using more than one TX Native instances

    const { tx, t, createNativeInstance } = require('@transifex/native');
    // Initiatate a secondary TX Instance
    const txOtherInstance = createNativeInstance();
      token: '<PUBLIC PROJECT TOKEN 2>',
    // initialize SDK
      token: '<PUBLIC PROJECT TOKEN>',
    // Use tx as a controller of the other instance
    // get all languages
    tx.setCurrentLocale('fr').then(function() {
      // translate something
      const message = t('Welcome {user}', {user: 'Joe'});
      const message2 = txOtherInstance.t('Welcome {user}', {user: 'Joe'});


    Licensed under Apache License 2.0, see LICENSE file.


    npm i @transifex/native

    DownloadsWeekly Downloads






    Unpacked Size

    1.58 MB

    Total Files


    Last publish


    • transifex