npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@transifex/native

v7.1.3

Published

i18n framework using Transifex Native

Downloads

109,961

Readme

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.

native

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

Webpack

import { tx, t } from '@transifex/native';

// initialize
tx.init({
  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'});
  console.log(message);

  // get supported languages in order to create a language picker
  const languages = await tx.getLanguages();
  console.log(languages);
  /*
  [{
    name: 'Greek',
    code: 'el',
    localized_name: 'Ελληνικά',
    rtl: false,
  },{
  ...
  }]
  */
}

main();

Node.js

const { tx, t } = require('@transifex/native');

// initialize
tx.init({
  token: '<PUBLIC PROJECT TOKEN>',
});

...

Browser

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@transifex/native/dist/browser.native.min.js"></script>
<script type="text/javascript">
  const tx = Transifex.tx;
  const t = Transifex.t;

  // initialize SDK
  tx.init({
    token: '<PUBLIC PROJECT TOKEN>',
  });

  // get all languages
  tx.setCurrentLocale('fr').then(function() {
    // translate something
    const message = t('Welcome {user}', {user: 'Joe'});
    console.log(message);
  });
</script>

API

Initialize library

tx.init({
  // Public project token, defaults to empty string
  token: String,

  // CDS endpoint, defaults to https://cds.svc.transifex.net
  cdsHost: String,

  // Fetch only strings that contain specific tags from CDS, e.g. "master,react"
  filterTags: String,

  // Fetch only strings matching translation status: reviewed,proofread,finalized
  filterStatus: 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,
})

Languages

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
tx.getLanguages().
  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
tx.setCurrentLocale('el').
  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
console.log(tx.getCurrentLocale())

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
  ...icu variables...
})


// Example
console.log(
  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,

  // Replace the existing string occurrences with the occurrences of this request
  overrideOccurrences: 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.

tx.invalidateCDS({
  // 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();

Events

Library for listening to various async events.

// listen to event
onEvent(type, function)
type:
  FETCHING_TRANSLATIONS
  TRANSLATIONS_FETCHED
  TRANSLATIONS_FETCH_FAILED
  LOCALE_CHANGED
  FETCHING_LOCALES
  LOCALES_FETCHED
  LOCALES_FETCH_FAILED

// 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();
txOtherInstance.init({
  token: '<PUBLIC PROJECT TOKEN 2>',
})

// initialize SDK
tx.init({
  token: '<PUBLIC PROJECT TOKEN>',
});

// Use tx as a controller of the other instance
tx.controllerOf(txOtherInstance);

// get all languages
tx.setCurrentLocale('fr').then(function() {
  // translate something
  const message = t('Welcome {user}', {user: 'Joe'});
  console.log(message);
  const message2 = txOtherInstance.t('Welcome {user}', {user: 'Joe'});
  console.log(message2);
});

License

Licensed under Apache License 2.0, see LICENSE file.