Lokalise APIv2 Node SDK

Node interface for the Lokalise APIv2.

Documentation navigation

Changelog

17.0.1 (23-Oct-2026)

17.0.0 (23-Oct-2026)

Example usage:

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

const api = new LokaliseApiVantage({
  apiKey: "your-api-key",
});

// List Vantage projects.
const projects = await api.projects().list({
  team_id: "your-team-uuid",
  limit: 10,
});

// Retrieve the next page.
const nextPage = await api.projects().list({
  team_id: "your-team-uuid",
  after: projects.cursor!,
});

// Get project languages.
const languages = await api.projectLanguages().list({
  project_id: "your-project-uuid",
});

For more details, see the Vantage API documentation.

16.6.0 (21-Sep-2026)

16.5.0 (17-Sep-2026)

16.4.1 (02-Sep-2026)

16.4.0 (19-Aug-2026)

Added support for the translation_engine parameter when creating a task. An automatic_translation task is performed by Lokalise AI by default; pass translation_engine to have a machine translation engine do it instead:

const task = await lokaliseApi.tasks().create(
	{
		title: "node mt task",
		task_type: "automatic_translation",
		translation_engine: "deepl", // "ai" (default), "google" or "deepl"
		keys: [key1, key2],
		source_language_iso: "en",
		languages: [{ language_iso: "de" }],
	},
	{ project_id: project_id },
);

The parameter is accepted only for automatic_translation tasks, and only when creating one: it is not part of UpdateTaskParams.

16.3.0 (17-Jul-2026)

Added support for the new Audit Logs endpoint.

Audit Logs are available through the new LokaliseApiV1 client:

const lokaliseApi = new LokaliseApiV1({
	apiKey: process.env.API_KEY,
});

Example:

const auditLogs = await lokaliseApi.auditLogs().list({
	// Optional parameters:
	limit: 100,
	cursor: "some_cursor",
	event_type: "project.deleted",
});

console.log(auditLogs.items);
console.log(auditLogs.items[0].metadata.event_code); // "project.deleted"
console.log(auditLogs.next_cursor);
console.log(auditLogs.has_more);

More endpoints will gradually become available through LokaliseApiV1.

16.2.0 (15-Jul-2026)

Added support for upload from FSS:

process = await lokaliseApi.files().uploadFromFss(project_id,
  {fss_file_id: 'fss_file_id', filename: 'test1.json', lang_iso: 'en'}
);

process.status; // => 'queued'

This imports a file previously uploaded to the Lokalise file storage service (FSS). Instead of passing the file content as base64-encoded data, the file is referenced by its storage file ID. The referenced file must have been stored owner-scoped under the same project ID with the importViaMCP use case. In all other aspects the endpoint behaves the same as the regular upload.

16.1.0 (13-Jul-2026)

16.0.0 (08-May-2026)

15.7.1 (06-Apr-2026)

15.7.0 (06-Apr-2026)

15.6.1 (29-Jan-2026)

15.6.0 (19-Dec-2025)

15.5.0 (18-Dec-2025)

15.4.0 (10-Nov-2025)

15.3.1 (14-Oct-2025)

15.3.0 (01-Oct-2025)

15.2.1 (14-Aug-2025)

15.2.0 (14-Aug-2025)

15.1.0 (13-Aug-2025)

15.0.0 (23-Jul-2025)

14.9.1 (02-Jul-2025)

14.9.0 (01-Jul-2025)

14.8.0 (27-May-2025)

14.7.0 (09-May-2025)

const client = new LokaliseApi({
  // other config ...
  silent: true,
});

14.6.0 (08-May-2025)

14.5.2 (05-May-2025)

14.5.1 (04-May-2025)

14.5.0 (30-Apr-2025)

const termObject = await lokaliseApi.glossaryTerms().get(termId, {
  project_id: projectId,
});

termObject.projectId; // => "123.abc"

14.4.0 (18-Apr-2025)

14.3.0 (12-Apr-2025)

14.2.1 (02-Apr-2025)

14.2.0 (20-Mar-2025)

const response = await lokaliseApi.files().download(projectId, params);

response.responseTooBig; // false

const keys = await lokaliseApi.keys().list({ project_id: projectId });

keys.responseTooBig; // true

14.1.0 (11-Mar-2025)

14.0.0 (04-Mar-2025)

13.2.1 (21-Feb-2025)

13.2.0 (17-Feb-2025)

13.1.0 (08-Feb-2025)

const process = await lokaliseApi
  .files()
  .async_download(projectId, params);

console.log(process.process_id);

The process is a QueuedProcess. Then you can simply fetch information about the process and grab the bundle URL:

const processInfo = await lokaliseApi
  .queuedProcesses()
  .get(process.process_id, { project_id: projectId });

processInfo.type; // => "async-export"
processInfo.status; // => "finished"
processInfo.details.total_number_of_keys; // => 14
processInfo.details.download_url // => "https://lokalise-live-lok-s3-fss-export.s3.eu-central-1.amazonaws.com/..."

13.0.0 (12-Dec-2024)

const client = new LokaliseApi({
  apiKey: "API_KEY",
  requestTimeout: 5e3, // the value is in milliseconds
});

try {
  await client.projects().list();
} catch (e) {
  console.error(e);
  console.log(e.message); // "Request timed out after 5000ms"
  console.log(e.code); // 408
  console.log(e.details); // { reason: "timeout" }
}

12.8.0 (15-Oct-2024)

const roles = await lokaliseApi.permissionTemplates().list({
  team_id: teamId,
});

const roleDetails = roles.items[0];

roleDetails.id // => 1
roleDetails.role // => "Manager"
roleDetails.tag // => "Full access"

const user_group = await lokaliseApi.userGroups().get(groupId, {
  team_id: teamId,
});

user_group.role_id; // => 5

const contributor = await lokaliseApi.contributors().get(userId, {
  project_id: projectId,
});

contributor.role_id; // => 5

12.7.0 (17-Jul-2024)

const task = await lokaliseApi.tasks().get(taskId, {
  project_id: projectId,
});

const language = task.languages[0];
language.tm_leverage.status; // => "completed"
language.tm_leverage.value["50%+"]; // => 31

12.6.0 (01-Jul-2024)

const teams = await lokaliseApi.teams().list();
const team = teams.items[0];

team.quota_allowed.ai_words // => 4000
team.quota_usage.ai_words // => 1234

12.5.0 (14-May-2024)

// 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

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,
});

12.4.1 (24-Apr-2024)

12.4.0 (25-Mar-2024)

12.3.0 (19-Mar-2024)

12.2.1 (13-Mar-2024)

12.2.0 (13-Mar-2024)

12.1.0 (05-Dec-2023)

12.0.0 (23-Sep-2023)

11.1.0 (19-Sep-2023)

11.0.1 (23-Aug-2023)

11.0.0 (23-Aug-2023)

10.0.0 (5-Jul-2023)

9.8.1 (23-May-2023)

8.5.1 (23-May-2023)

9.8.0 (29-Mar-2023)

8.5.0 (29-Mar-2023)

9.7.0 (16-Mar-2023)

8.4.0 (16-Mar-2023)

9.6.1 (02-Mar-2023)

9.6.0 (28-Jan-2023)

8.3.0 (28-Jan-2023)

9.5.0 (11-Jan-2023)

const response = await lokaliseApi.jwt().create("1234.abcd");

response.jwt // => "eyJ0eXAiOiJKV1QiLCJhbG..."

9.4.0 (30-Dec-2022)

9.3.0 (30-Nov-2022)

const response = await lokaliseApi.jwt().get();

response.jwt // => "eyJ0eXAiOiJKV1QiLCJhbG"

9.2.0 (20-Oct-2022)

9.1.0 (13-Oct-2022)

9.0.0 (05-Oct-2022)

8.2.0 (20-Oct-2022)

8.1.0 (13-Oct-2022)

8.0.2 (03-Oct-2022)

// We can import the Contributor interface easily:
import { LokaliseApi, Contributor } from '@lokalise/node-api';

const lokaliseApi = new LokaliseApi({ apiKey: '123xyz' });

const contributors = await lokaliseApi.contributors().create([
  {
    // ...
  }
], { project_id: '123.abc' });

const contributor: Contributor = contributors[0];
console.log(contributor.email, contributor.user_id);

import {
  RequestTokenResponse,
  RefreshTokenResponse,
  LokaliseAuth
} from '@lokalise/node-api';

const lokaliseAuth = new LokaliseAuth("123abc", "456zyx");

const token_resp: RequestTokenResponse = await lokaliseAuth.token("secret_code");

const refresh_resp: RefreshTokenResponse = await lokaliseAuth.refresh("refresh_token");

8.0.1 (01-Sep-2022)

8.0.0 (01-Aug-2022)

const keys = await lokaliseApi.keys().create(
  {
    keys: [
      {
        key_name: "welcome_web",
        description: "Index app welcome",
        platforms: ["web"],
        filenames: {
          web: "my_filename.json",
        },
        translations: [
          {
            language_iso: "en",
            translation: "Welcome",
          },
        ],
      },
      {
        key_name: "welcome_ios",
        description: "Welcome apple",
        platforms: ["ios"],
        is_plural: true,
        translations: [
          {
            language_iso: "en",
            translation: {
              one: "I have one apple",
              other: "I have a lot of apples",
            },
          },
        ],
      },
    ],
  },
  { project_id: project_id }
);


// Per-platform key names:

const keys = await lokaliseApi.keys().create(
  {
    keys: [
      {
        key_name: {
          ios: "name_for_ios",
          web: "name_for_web",
          android: "android_name",
          other: "other_name",
        },
        platforms: ["web", "ios"],
        translations: [
          {
            language_iso: "en",
            translation: "Per-platform key names",
          },
        ],
      },
    ],
  },
  { project_id: project_id }
);

const keys = await lokaliseApi.keys().bulk_update(
  {
    keys: [
      {
        key_id: key_id,
        description: "Bulk node",
        platforms: ["web"],
      },
      {
        key_id: second_key_id,
        description: "Second bulk",
      },
    ],
  },
  { project_id: project_id }
);

const client = new LokaliseApi({
  apiKey: "123abc",
  host: "https://custom.example.com/api2/",
});

7.3.1 (07-Jun-2022)

7.3.0 (07-Jun-2022)

7.2.0 (08-Mar-2022)

const { LokaliseAuth } = require('@lokalise/node-api');

// Provide your client id and client secret
const lokaliseAuth = new LokaliseAuth("client id", "client secret");

// Generate an authentication url
const url = lokaliseAuth.auth(
  ["read_projects", "write_team_groups"],
  "http://example.com/redirect",
  "random123"
);

// Generate an authentication and refresh tokens
const response = await lokaliseAuth.token("secret code");
const token = response["access_token"];
const refresh_token = response["refresh_token"];

// Refresh an access token once it expires
const new_token = await lokaliseAuth.refresh(refresh_token)["access_token"];

// Perform requests on the user's behalf
const { LokaliseApiOAuth } = require('@lokalise/node-api');

const lokaliseApi = new LokaliseApiOAuth({ apiKey: new_token });

const projects = lokaliseApi.projects().list();

7.1.1 (21-Feb-2022)

7.1.0 (17-Dec-2021)

7.0.1 (10-Nov-2021)

7.0.0 (25-Oct-2021)

lokaliseApi.comments.list_project_comments()

lokaliseApi.files.upload()

lokaliseApi.comments().list_project_comments() // .comments(), not .comments

lokaliseApi.files().upload() // .files(), not .files

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

const projects = lokaliseApi.projects().list();

6.3.0 (15-Jul-21)

6.2.2 (13-Jul-21)

6.2.1 (18-May-21)

6.2.0 (28-Apr-21)

6.1.0 (26-Feb-21)

6.0.0 (02-Feb-21)

This is a major release that contains quite a lot of changes mostly aimed towards pagination and typings system. Also the docs were updated, and various fixes were introduced.

Breaking change: pagination data is now attached directly to the collection returned by the request. Previously the following code was not working because pagination was stored in a separate object unrelated to the collection:

const projects = lokaliseApi.projects.list({team_id: team_id, page: 2, limit: 10});
projects.totalResults; // => undefined

Therefore, you had to do the following inconvenient trick (for example, see #53):

lokaliseApi.projects.list().totalResults;

This is not the case anymore! Paginated collections now have the following attributes and functions:

projects.totalResults; // => 30
projects.totalPages; // => 3
projects.resultsPerPage; // => 10
projects.currentPage; // => 2
projects.hasNextPage(); // => true
projects.hasPrevPage(); // => true
projects.isLastPage(); // => false
projects.isFirstPage(); // => false
projects.nextPage(); // => 3
projects.prevPage(); // => 1

However to get the actual data from the paginated response, you must use the .items attribute now:

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

// 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]; // this will not work anymore!
project.name

// And pagination can be fetched in the following way:
projects.totalResults; // => 30
projects.hasNextPage(); // => true

Breaking change: potential errors returned by the API when performing bulk create or bulk update operations are not swallowed anymore. For example, Lokalise APIv2 allows to create translation keys in bulk. If one of the key names is already taken, it won’t be created and the corresponding error message will be added to the errors response attribute. However, the whole operation will not fail and all other valid keys will still be created. The response has the following structure:

{
    "project_id": "300abc.877xyz",
    "keys": [
      // keys that were successfully created
    ],
    "errors": [
        {
            "message": "This key name is already taken",
            "code": 400,
            "key": {
                "key_name": "button.ok" // this key name cannot be created because of the duplicating name
            }
        }
    ]
}

Previously such errors were silently swallowed, however that’s not the case anymore. Specifically, changes were made to the following methods:

To fetch the actual data returned by these methods you now have to use the .items attribute. To fetch the errors, use .errors:

const keys = await lokaliseApi.keys.create(
  [
    {
      key_name: "valid.key.name",
      platforms: ["web"],
      filenames: { web: "%LANG_ISO%.yml", },
      translations: [
        {
          language_iso: "en",
          translation: "Valid key",
        },
      ],
    },
    {
      key_name: "duplicate.key",
      platforms: ["web"],
      translations: [
        {
          language_iso: "en",
          translation: "Duplicate!",
        },
      ],
    },
  ],
  { project_id: '123.abc' }
);

keys.errors[0].message // => "This key name is already taken" -- this key was not created
keys.items[0].key_name.ios // => "valid.key.name" -- this key was created

Update: added auto_close_items boolean attribute for Task.

5.3.0 (24-Nov-20)

5.2.2 (09-Nov-20)

5.2.1 (03-Nov-20)

5.2.0 (02-Oct-20)

5.1.0 (09-Sep-20)

5.0.0 (08-Jul-20)

lokaliseApi.branches.merge(34567,
  {project_id: '123.abc'},
  {"force_conflict_resolve_using": "master"}
)

4.0.1 (16-Jun-20)

4.0.0 (18-May-20)

3.0.3 (22-Apr-20)

3.0.0 (27-Mar-20)

2.1.0 (28-Feb-20)

2.0.2 (25-Feb-20)

2.0.1 (09-Dec-19)

2.0.0 (05-Dec-19)

1.5.0-rc.1 (04-Dec-19)

1.4.0 (13-Nov-19)

1.3.0 (30-Oct-19)

1.2.0 (20-Aug-19)

1.1.0 (18-Jul-19)

1.0.1 (12-07-19)

1.0.0 (20-06-19)

Note that this version is a major re-write and has API breaking changes! Check documentation for the specific endpoint to learn more.

0.0.9 (07-06-19)

0.0.4