JavaScript

Quickstart: Transifex Native and JavaScript

This is a quick start guide to get you through the whole Transifex Native experience on JavaScript. Follow the steps below to start testing Transifex Native on your JavaScript project.

Install JavaScript SDK

To complete this step you will need to install the JavaScript libraries using the following command in your project’s root folder:

$ npm install @transifex/native @transifex/cli --save

This will install the vanilla Transifex Native for JavaScript SDK and a command line tool for pushing source phrases to Transifex for localization.

📘

Supported node.js versions are 12.x.x and above.

Initialize the SDK

You can use the SDK in your Webpack project, directly in Node.js or use the precompiled libraries and reference them directly into your browser’s code. Here are some examples on how this can be done in various environments.

Webpack

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

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

Node.js

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

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;

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

Internationalize your code

Internationalization of code happens through the use of the t function. Transifex Native localization framework is using the ICU syntax to describe localization rules. Additionally you can define certain metadata parameters per string, like context, tags or character limit. Here is a quick example:

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

t('Hello!');

t('Hello {username}', { username: 'Joe' });

t('Hello {username}', { 
  _context: 'dashboard page',
  username: 'Joe', 
});

Push source content to Transifex

Use @transifex/cli library to collect all translatable strings and push them to Transifex using the following command:

$ ./node_modules/.bin/txjs-cli push src/ --token=<PROJECT TOKEN> --secret=<PROJECT SECRET>

Translate Content on Transifex

After content is added in your Transifex project you and your team can use all the available tools that Transifex offers. Check these starting points for your localization team:

When a new translation is added in Transifex, it becomes available over-the-air on your Transifex Native enabled application.

The service delivering the translations to your application is called the Content Delivery Service and it's an active part of the Transifex Native solution, see more about Transifex Content Delivery Service.

Display translated content

To display the content in the target translation language use the tx.setCurrentLocale function, returning a Promise that resolves when content is loaded over the air from Transifex.

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

tx.setCurrentLocale('el')
  .then(() => {
    console.log('el translations loaded');
    console.log(t('Hello')); // -> 'Γειά'
  })
  .catch(err => console.log(err));

Segments rendered by previous invocations of the t function will not be rerendered to reflect the change in language. For this purpose you can subscribe to events exposed by the SDK:

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

let element = document.getElementById('message');

const renderMsg = () => { element.innerHTML = t('Hello'); };
renderMsg();  // -> 'Hello'
onEvent(LOCALE_CHANGED, renderMsg);  // -> 'Γεια'

To get a list of supported languages (e.g. in order to create a language selector) use the tx.getLanguages function.

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

tx.getLanguages().then((languages) => {
  console.log(languages); 
  // [{
  //   name: 'Greek',
  //   code: 'el',
  //   localized_name: 'Ελληνικά',
  //   rtl: false,
  // }, {
  //   ...
  // }]
});

For a quick overview of JavaScript supported Native features checkout the Transifex Native Feature Matrix.