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 need 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.

All object attributes can 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

Cursor pagination

The List Keys and List Translations endpoints support cursor pagination, which is recommended for its faster performance compared to traditional “offset” pagination. By default, “offset” pagination is used, so you must explicitly set pagination to "cursor" to use cursor pagination.

// This approach is also applicable for `lokaliseApi.translations().list()`
const keys = await lokaliseApi.keys().list({
  project_id: projectId,
  limit: 2, // The number of items to fetch. Optional, default is 100
  pagination: "cursor",
  cursor: "eyIxIjo1MjcyNjU2MTd9", // The starting cursor. Optional, string
});

const key = keys.items[0]; // Accessing items as with regular pagination

After retrieving data from the Lokalise API, you can check for the availability of the next cursor and proceed accordingly:

const hasNext = keys.hasNextCursor(); // Returns a boolean

const nextCursor = keys.nextCursor; // Returns the next cursor as a string, empty if unavailable

const keysNextPortion = await lokaliseApi.keys().list({
  project_id: projectId,
  limit: 2,
  pagination: "cursor",
  cursor: nextCursor,
});

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.