dies / ota-client-js

JavaScript client library for Crowdin Over-The-Air Content Delivery

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.

Status

Build Status

Azure CI (Linux)	Azure CI (Windows)	Azure CI (MacOS)

Table of Contents

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

Installation

npm

npm i @crowdin/ota-client

yarn

yarn add @crowdin/ota-client

Quick Start

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 (Content Delivery tab) 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

You also can customize client for your needs. In constructor as a second (optional) argument you can pass configuration object.

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 v2 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 = '7a0c1ee2622bc85a4030297uo3b';

const client = new otaClient(hash, config);

Contributing

If you want 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.

If you've found an error in these samples, please Contact Customer Success Service.

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.