Crowdin OTA JavaScript client  

Lightweight library for Crowdin Over-The-Air Content Delivery. The best way to deliver translations to your site Over-The-Air 💫

Information about Crowdin OTA can be found in the Knowledge Base article. Also, visit the Wiki to read more about the advanced usage of OTA Client.

Live Demo  |  OTA JS Client Docs  |  Examples

Works with

Table of Contents

• Installation
• Quick Start
• Using Bundles
• Contributing
• Seeking Assistance
• License

Installation

npm

npm i @crowdin/ota-client

yarn

yarn add @crowdin/ota-client

Quick Start

Creating a distribution

Distribution is a CDN vault that mirrors the translated content of your project. Thanks to the CDN (Content Delivery Network), the translated content will become available to users much faster.

To create a distribution, open Tools > Content Delivery in your Crowdin project and click the Add distribution button. Then type a name, select the files translations for which you want to be shown in your application, select export options, and click Next. Copy the distribution hash so you can use it for integration.

For more information about the "Bundle" export option click Using bundles.

Usage

Typescript

import otaClient from '@crowdin/ota-client';

// distribution hash
const hash = '{distribution_hash}';

// initialization of crowdin ota client
const client = new otaClient(hash);

// get list of files in distribution
client.listFiles()
  .then(file => console.log(file))
  .catch(error => console.error(error));

// one of target languages in Crowdin project (could be retrieved via client.listLanguages)
const languageCode = 'uk';
// one of files from client.listFiles
const file = 'file';
// get file translations
client.getFileTranslations(file, languageCode)
  .then(translations => console.log(translations))
  .catch(error => console.error(error));

Javascript ES6 modules

import otaClient from '@crowdin/ota-client';
// or const otaClient = require('./out/index.js').default;

// distribution hash
const hash = '{distribution_hash}';

// initialization of crowdin ota client
const client = new otaClient(hash);

// get list of files in distribution
client.listFiles()
  .then(file => console.log(file))
  .catch(error => console.error(error));

// one of target languages in Crowdin project (could be retrieved via client.listLanguages)
const languageCode = 'uk';
// one of files from client.listFiles
const file = 'file';
// get file translations
client.getFileTranslations(file, languageCode)
  .then(translations => console.log(translations))
  .catch(error => console.error(error));

Javascript CommonJS

const otaClient = require('@crowdin/ota-client').default;

// distribution hash
const hash = '{distribution_hash}';

// initialization of crowdin ota client
const client = new otaClient(hash);

// get list of files in distribution
client.listFiles()
  .then(file => console.log(file))
  .catch(error => console.error(error));

// one of target languages in Crowdin project (could be retrieved via client.listLanguages)
const languageCode = 'uk';
// one of files from client.listFiles
const file = 'file';
// get file translations
client.getFileTranslations(file, languageCode)
  .then(translations => console.log(translations))
  .catch(error => console.error(error));

You can create a new distribution in your Crowdin project settings (Tools > Content Delivery) or using Distributions API through REST API. After that you will receive a Distribution hash.

Client methods

Client contains methods to retrieve translation strings from files as a plain text and from JSON files as an objects. Also, there are several helper methods.

Method name	Description	Input arguments
Methods for plain text
getTranslations	Returns translations for all languages
getLanguageTranslations	Returns translations for specific language	languageCode (optional, otherwise use setCurrentLocale)
getFileTranslations	Returns translations for specific language and file	file (e.g. one from listFiles), languageCode (optional, otherwise use setCurrentLocale)
Methods for JSON-based files
getStrings	Returns translations for all languages	file (optional, e.g. json file from listFiles)
getStringsByLocale	Returns translations for specific language	file (optional, e.g. json file from listFiles), languageCode (optional, otherwise use setCurrentLocale)
getStringByKey	Returns translation for language for specific key	key, file (optional, e.g. json file from listFiles), languageCode (optional, otherwise use setCurrentLocale)
Helper methods
getHash	Returns distribution hash
setCurrentLocale	Define global language for client instance	languageCode
getCurrentLocale	Get global language for client instance
getManifestTimestamp	Get manifest timestamp of distribution
listFiles	List of files in distribution
listLanguages	List of project language codes
getReplacedLanguages	List of project language codes in the provided format	format (placeholder format you want to replace your languages with, e.g. locale)
getReplacedFiles	List of files in distribution with variables replaced with the corresponding language code
getLanguageObjects	List of project language objects
clearStringsCache	Clear cache of translation strings
getLanguageMappings	Get project language mapping
getCustomLanguages	Get project custom languages

Example of loading strings from JSON files:

import otaClient from'@crowdin/ota-client';

const hash = '{distribution_hash}';

const client = new otaClient(hash);

// will return all translation strings for all languages from all json files
client.getStrings()
  .then(res => {
    //get needed translation by language + key
    console.log(res.uk.application.title);
  })
  .catch(error => console.error(error));

// or get concrete translation by key
client.getStringByKey(['application', 'title'], '/folder/file.json', 'uk')
  .then(title => console.log(title))
  .catch(error => console.error(error));

// or define global language and do not pass it everywhere
client.setCurrentLocale('uk');
client.getStringByKey(['application', 'title'], '/folder/file.json')
  .then(title => console.log(title))
  .catch(error => console.error(error));

Client configuration

There is a possibility to customize Client for your needs. You can pass a configuration object as a second (optional) argument in the constructor.

Config option	Description	Example
hash	Distribution Hash	7a0c1ee2622bc85a4030297uo3b
httpClient	Custom HTTP client	Axios (default)
disableManifestCache	Disable caching of manifest file which will lead to additional request for each client method	true
languageCode	Default language code to be used if language was not passed as an input argument of the method (also possible via setCurrentLocale method)	uk
disableStringsCache	Disable caching of translation strings which is used for JSON-based client methods	true
disableLanguagesCache	Disable caching of Crowdin's language list	true
disableJsonDeepMerge	Disable deep merge of json-based files for string-based methods and use shallow merge	true
enterpriseOrganizationDomain	The domain of your Crowdin enterprise organization. If provided, the client will use the Crowdin Enterprise API endpoint to fetch languages, as opposed to the regular API when missing.	organization_domain

import otaClient, { ClientConfig } from'@crowdin/ota-client';

const config: ClientConfig = {
  httpClient: customHttpClient,
  disableManifestCache: true,
  languageCode: 'uk',
  disableStringsCache: true,
  disableJsonDeepMerge: true
};

const hash = '{distribution_hash}';

const client = new otaClient(hash, config);

Using Bundles

Bundles allow exporting sets of strings in one of the selected formats. In simple words, bundles are translation files that include sets of strings formed based on the specified patterns during distribution setup.

By default, you can choose from the following three formats: XLIFF, Android XML, and iOS Strings. Additionally, you can add more target file formats by installing respective applications from the Crowdin Marketplace.

To use the Bundles feature, select the Bundle export option on the distribution setup.

Contributing

If you would like to contribute please read the Contributing guidelines.

Seeking Assistance

If you find any problems or would like to suggest a feature, please feel free to file an issue on Github at Issues Page.

License

The Crowdin OTA JavaScript client is licensed under the MIT License.
See the LICENSE.md file distributed with this work for additional
information regarding copyright ownership.

Except as contained in the LICENSE file, the name(s) of the above copyright
holders shall not be used in advertising or otherwise to promote the sale,
use or other dealings in this Software without prior written authorization.