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
npm i @crowdin/ota-client
yarn add @crowdin/ota-client
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.
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 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));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);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.
If you would like to contribute please read the Contributing guidelines.
If you find any problems or would like to suggest a feature, please feel free to file an issue on Github at Issues Page.
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.