Getting Started

Installation and Requirements

Please note that starting from version 9 this SDK is a pure ESM module. It does not provide a CommonJS export (require) anymore. Therefore you should either convert your project to ESM, use dynamic import, or stay on version 8 which we are fully supporting.

This library requires Node 14 and above. Install it with NPM:

npm install @lokalise/node-api

Initializing the Client

If you’d like to work with the OTA (over-the-air) endpoints, please refer to the OTA introduction article.

In order to perform API requests, you require a special token that can be obtained in your personal profile (API tokens section).

After you’ve obtained the token, initialize the client:

import { LokaliseApi } from "@lokalise/node-api";

const lokaliseApi = new LokaliseApi({ apiKey: '<apiKey>'});

Alternatively, you can use tokens obtained via OAuth2 (don’t forget that these tokens have expiration dates):

import { LokaliseApiOAuth } from "@lokalise/node-api";

const lokaliseApi = new LokaliseApiOAuth({ apiKey: '<apiKeyObtainedViaOauth2>' });

Now you can perform API requests, for example:

const projects = await lokaliseApi.projects().list();
projects.items[0].name;

Every request returns a promise with a corresponding object (or array of objects) as the result. Please note that Lokalise API locks parallel requests which means you should call methods in a synchronous manner.

All object attributes may be found in the interfaces.

Pagination

Bulk fetches support pagination. There are two common parameters available:

• limit (defaults to 100, maximum is 5000) — number of records to display per page
• page (defaults to 1) — page to fetch

For instance:

const projects = lokaliseApi.projects().list({page: 2, limit: 10});

The response pagination data can be fetched in the following way:

projects.totalResults; // => 30
projects.totalPages; // => 3
projects.resultsPerPage; // => 10
projects.currentPage; // => 2

You can also utilize the following functions:

projects.hasNextPage(); // => true
projects.hasPrevPage(); // => true
projects.isLastPage(); // => false
projects.isFirstPage(); // => false
projects.nextPage(); // => 3
projects.prevPage(); // => 1

Please note that in order to get the actual data from the paginated response, you have to use the .items attribute:

// CORRECT:
const project = projects.items[0]; // .items will fetch all projects data and [0] will get the first project
project.name

// INCORRECT:
const project = projects[0];
project.name

Branching

If you are using project branching feature, simply add branch name separated by semicolon to your project ID in any endpoint to access the branch. For example, in order to access new-feature branch for the project with an id 123abcdef.01:

lokaliseApi.files().list({project_id: '123abcdef.01:new-feature'});

Compression

Lokalise API supports gzip compression. By default it’s turned off but you can enable it by setting the enableCompression option:

new LokaliseApi({ apiKey: "123abc", enableCompression: true })

When this option is set to true, it will add an Accept-Encoding=gzip,deflate header to the request. It can be very useful when requesting a large amount of data.