@lokalise/node-api

What is @lokalise/node-api?

@lokalise/node-api is an official Node.js client for the Lokalise API, which allows developers to interact with the Lokalise platform programmatically. Lokalise is a translation management system that helps teams manage localization projects. This package provides a way to automate tasks such as managing projects, uploading and downloading files, and handling translations.

What are @lokalise/node-api's main functionalities?

Managing Projects

This feature allows you to create and manage projects on Lokalise. The code sample demonstrates how to create a new project with a specified name, description, and languages.

const LokaliseApi = require('@lokalise/node-api');
const lokaliseApi = new LokaliseApi({ apiKey: 'your_api_key' });

async function createProject() {
  const project = await lokaliseApi.projects.create({
    name: 'New Project',
    description: 'A new project description',
    languages: [{ lang_iso: 'en' }]
  });
  console.log(project);
}

createProject();

Uploading Files

This feature allows you to upload translation files to a specific project. The code sample demonstrates how to upload a file by providing the project ID, base64 encoded file content, filename, and language ISO code.

const LokaliseApi = require('@lokalise/node-api');
const lokaliseApi = new LokaliseApi({ apiKey: 'your_api_key' });

async function uploadFile() {
  const upload = await lokaliseApi.files.upload('project_id', {
    data: 'base64_encoded_file_content',
    filename: 'translations.json',
    lang_iso: 'en'
  });
  console.log(upload);
}

uploadFile();

Downloading Files

This feature allows you to download translation files from a specific project. The code sample demonstrates how to download files by providing the project ID and specifying the format and whether to use original filenames.

const LokaliseApi = require('@lokalise/node-api');
const lokaliseApi = new LokaliseApi({ apiKey: 'your_api_key' });

async function downloadFile() {
  const download = await lokaliseApi.files.download('project_id', {
    format: 'json',
    original_filenames: true
  });
  console.log(download);
}

downloadFile();

Handling Translations

This feature allows you to handle translations within a project. The code sample demonstrates how to add a new translation key with its corresponding translations by providing the project ID, key name, and translations.

const LokaliseApi = require('@lokalise/node-api');
const lokaliseApi = new LokaliseApi({ apiKey: 'your_api_key' });

async function addTranslation() {
  const translation = await lokaliseApi.keys.create('project_id', {
    keys: [{
      key_name: 'welcome_message',
      translations: [{
        language_iso: 'en',
        translation: 'Welcome!'
      }]
    }]
  });
  console.log(translation);
}

addTranslation();

Other packages similar to @lokalise/node-api

i18next

i18next is a popular internationalization framework for JavaScript. It provides a complete solution for localizing applications, including support for translation files, language detection, and interpolation. Compared to @lokalise/node-api, i18next focuses more on the client-side implementation of localization rather than managing translation projects.

gettext-parser

gettext-parser is a library for parsing and compiling gettext files (PO and MO files). It is useful for applications that use gettext for localization. While @lokalise/node-api provides a comprehensive API for managing translation projects on Lokalise, gettext-parser is more focused on handling gettext file formats.

node-polyglot

node-polyglot is a lightweight internationalization library for Node.js. It provides a simple way to manage translations and supports interpolation and pluralization. Compared to @lokalise/node-api, node-polyglot is more suitable for small-scale localization needs and does not offer project management features.

README

Lokalise API v2 official Node.js client

Official Node interface for the Lokalise API.

Index

• Getting started
  • Installation
  • Initializing Client
  • Branching
  • Pagination
• Usage
  • Branches
  • Comments
  • Contributors
  • Files
  • Keys
  • Languages
  • Orders
  • Payment cards
  • Projects
  • QueuedProcesses
  • Screenshots
  • Snapshots
  • Tasks
  • Teams
  • Team users
  • Team user groups
  • Translations
  • Translation Providers
  • Translation Statuses
  • Webhooks
• Additional Info
• Running Tests
• Building

Getting started

Installation

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

npm install @lokalise/node-api

Initializing Client

In order to perform API requests, you require a special token that can be obtained in your personal profile (API tokens section). Note that the owner of the token must have admin access rights.

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

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

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

Now you may perform API requests, for example:

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

All object attributes may be found in the interfaces.

Please note that Lokalise API locks parallel requests which means you should call methods in a synchronous manner.

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

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:

lokaliseApi.translationProviders.list({team_id: team_id, page: 2, limit: 10});

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

lokaliseApi.projects.totalResults;
lokaliseApi.projects.totalPages;
lokaliseApi.projects.resultsPerPage;
lokaliseApi.projects.currentPage;

Usage

Every request returns a promise with a corresponding object (or array of objects) as the result.

Branches

Documentation

List branches

lokaliseApi.branches.list({project_id: project_id});

Retrieve branch

lokaliseApi.branches.get(branch_id, {project_id: project_id});

Create branch

lokaliseApi.branches.create(
  {"name": "hotfix/really-important"},
  { project_id: project_id}
);

Update branch

lokaliseApi.branches.update(branch_id,
  {"name": "hotfix/not-really-important"},
  {project_id: project_id}
);

Delete branch

lokaliseApi.branches.delete(branch_id, {project_id: project_id});

Merge branch

lokaliseApi.branches.merge(branch_id_to_merge,
  {project_id: project_id},
  {"force_conflict_resolve_using": "master"}
)

Comments

Documentation

List project comments

lokaliseApi.comments.list_project_comments({ project_id: project_id });

List key comments

lokaliseApi.comments.list({project_id: project_id, key_id: key_id})

Retrieve a comment

lokaliseApi.comments.get(comment_id, {project_id: project_id, key_id: key_id});

Create project comments

lokaliseApi.comments.create({
  'comments': [
    { comment: "Project comment 1" },
    { comment: "Project comment 2" }
  ]
}, { project_id: project_id, key_id: key_id});

Delete a comment

lokaliseApi.comments.delete(comment_id, {project_id: project_id, key_id: key_id});

Contributors

Documentation

List project contributors

lokaliseApi.contributors.list({project_id: project_id});

Get a contributor

lokaliseApi.contributors.get(user_id, {project_id: project_id});

Create contributors

lokaliseApi.contributors.create([
  {
    "email": "[e-mail]",
    "fullname": "Mr. Translator",
    "is_admin": false,
    "is_reviewer": true,
    "languages": [
      {
        "lang_iso": "en",
        "is_writable": false
      }
    ]
  }
], {project_id: project_id});

Update contributor

lokaliseApi.contributors.update(
  user_id,
  {is_admin: true},
  {project_id: project_id}
);

Delete a contributor

lokaliseApi.contributors.delete(user_id, {project_id: project_id});

Translation files

Documentation

List project files

lokaliseApi.files.list({project_id: project_id});

Upload a file

Background uploading is the only method of importing files since July 2020.

process = await lokaliseApi.files.upload(project_id,
  {data: data_base64, filename: 'test1.json', lang_iso: 'en'})
process.status // => 'queued'

Asynchronous upload will return a QueuedProcess containing process ID, status of the process (queued, finished, failed etc) and some other info. You may periodically check the status of the process by using get() method:

// You'll obtain `process_id` after calling `upload()`
process = await lokaliseApi.queuedProcesses.get(process.process_id, { project_id: project_id })

process.status // => 'finished'

Download a file

lokaliseApi.files.download(project_id, {format: 'json', "original_filenames": true});

Keys

Documentation

List keys

lokaliseApi.keys.list({project_id: project_id});

Retrieve key

lokaliseApi.keys.get(key_id, {project_id: project_id});

Create keys

lokaliseApi.keys.create([
  {
    "key_name": "welcome_web",
    "description": "Index app welcome",
    "platforms": ["web"],
    "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});

Update a key

lokaliseApi.keys.update(key_id, {
  "platforms": ["web", "other"],
  "description": "Node updated"
}, { project_id: project_id });

Update keys in bulk

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

Delete a key

lokaliseApi.keys.delete(key_id, { project_id: project_id });

Delete multiple keys

lokaliseApi.keys.bulk_delete([
  key_id, second_key_id
], { project_id: project_id });

Languages

Documentation

List system languages

lokaliseApi.languages.system_languages();

List project languages

lokaliseApi.languages.list({project_id: project_id});

Retrieve a language

lokaliseApi.languages.get(lang_id, {project_id: project_id});

Create languages

lokaliseApi.languages.create([
  {
    "lang_iso": "ak"
  }
], { project_id: project_id });

Update a language

lokaliseApi.languages.update(lang_id, {
  "lang_name": "Chinese Traditional Custom"
}, { project_id: project_id });

Delete a language

lokaliseApi.languages.delete(lang_id, { project_id: project_id });

Orders

Documentation

List orders

lokaliseApi.orders.list({team_id: team_id})

Retrieve order

lokaliseApi.orders.get(order_id, {team_id: team_id})

Create order

lokaliseApi.orders.create({
  project_id: '803xyz145ba90b42abc.46800',
  card_id: '1774',
  briefing: 'My briefing',
  source_language_iso: 'en',
  target_language_isos: ['nl'],
  keys: [12345],
  provider_slug: 'gengo',
  translation_tier: '1'
},
{team_id: team_id});

Payment Cards

Documentation

List payment cards

lokaliseApi.paymentCards.list();

Retrieve payment card

lokaliseApi.paymentCards.get(card_id);

Create payment card

lokaliseApi.paymentCards.create({
  number: '4242424242424242',
  cvc: 123,
  exp_month: 10,
  exp_year: 2030
});

Delete payment card

lokaliseApi.paymentCards.delete(card_id);

Projects

Documentation

List projects

lokaliseApi.projects.list();

Retrieve project

lokaliseApi.projects.get(project_id)

Create project

lokaliseApi.projects.create({ name: "Project name", description: "Project description" });

Update project

lokaliseApi.projects.update(project_id, { name: "New name", description: "New description"});

Empty project

lokaliseApi.projects.empty(project_id)

Delete project

lokaliseApi.projects.delete(project_id);

Queued Processes

Documentation

List queued processes

lokaliseApi.queuedProcesses.list({ project_id: project_id })

Retreive queued process

lokaliseApi.queuedProcesses.get(process_id, { project_id: project_id })

Screenshots

Documentation

List screenshots

lokaliseApi.screenshots.list({project_id: project_id});

Retrieve screenshot

lokaliseApi.screenshots.get(screenshot_id, {project_id: project_id});

Create screenshots

lokaliseApi.screenshots.create([
  {
    data: data,
    "ocr": false,
    "key_ids": [key_id],
    "tags": ["onboarding"]
  }
],{project_id: project_id});

Update a screenshot

lokaliseApi.screenshots.update(screenshot_id,
  {title: 'node screen', description: 'node desc'},
  {project_id: project_id}
);

Delete a screenshot

lokaliseApi.screenshots.delete(screenshot_id, {project_id: project_id});

Snapshots

Documentation

List snapshots

lokaliseApi.snapshots.list({project_id: project_id});

Create a snapshot

lokaliseApi.snapshots.create({"title": "API snapshot"}, {project_id: project_id});

Restore a snapshot

lokaliseApi.snapshots.restore(snapshot_id, {project_id: project_id});

Delete a snapshot

lokaliseApi.snapshots.delete(snapshot_id, {project_id: project_id});

Tasks

Documentation

List tasks

lokaliseApi.tasks.list({project_id: project_id});

Retrieve task

lokaliseApi.tasks.get(task_id, {project_id: project_id});

Create a task

lokaliseApi.tasks.create({
  title: 'node task',
  keys: [key1, key2],
  languages: [
    {
      "language_iso": "en",
      "users": [user1, user2]
    }
  ]
}, {project_id: project_id});

Update a task

lokaliseApi.tasks.update(
  task_id,
  {title: 'node updated'},
  {project_id: project_id}
);

Delete a task

lokaliseApi.tasks.delete(task_id, {project_id: project_id});

Teams

Documentation

List all teams

lokaliseApi.teams.list();

Team users

Documentation

List team users

lokaliseApi.teamUsers.list({team_id: team_id});

Retrieve a team user

lokaliseApi.teamUsers.get(user_id, {team_id: team_id});

Update a team user

lokaliseApi.teamUsers.update(
  user_id,
  {role: 'admin'},
  {team_id: team_id}
);

Delete a team user

lokaliseApi.teamUsers.delete(user_id, {team_id: team_id});

Team user groups

Documentation

List team user groups

lokaliseApi.userGroups.list({team_id: team_id});

Retrieve team user group

lokaliseApi.userGroups.get(group_id, {team_id: team_id});

Create a team user group

lokaliseApi.userGroups.create(
  {
    name: 'Node',
    is_reviewer: false,
    is_admin: true,
    admin_rights: ['upload']
  },
  {team_id: team_id}
);

Update team user group

lokaliseApi.userGroups.update(
  group_id,
  {
    name: 'Node updated',
    is_reviewer: false,
    is_admin: true,
    admin_rights: ['upload']
  },
  {team_id: team_id}
);

Add projects to a group

lokaliseApi.userGroups.add_projects_to_group(
  team_id,
  group_id,
  [project_id]
);

Remove projects from a group

lokaliseApi.userGroups.remove_projects_from_group(
  team_id,
  group_id,
  [project_id]
);

Add users to a group

lokaliseApi.userGroups.add_members_to_group(
  team_id,
  group_id,
  [user_id]
);

Remove users from a group

lokaliseApi.userGroups.remove_members_from_group(
  team_id,
  group_id,
  [user_id]
);

Delete group

lokaliseApi.userGroups.delete(new_group_id, {team_id: team_id});

Translations

Documentation

List translations

lokaliseApi.translations.list({project_id: project_id});

Retrieve translation

lokaliseApi.translations.get(translation_id, {project_id: project_id});

Update translation

lokaliseApi.translations.update(
  translation_id,
  {translation: 'updated'},
  {project_id: project_id}
);

Translation Providers

Documentation

List translation providers

lokaliseApi.translationProviders.list({team_id: team_id})

Retrieve translation provider

lokaliseApi.translationProviders.get(translation_provider_id, {team_id: team_id});

Translation Statuses

Documentation

List translation statuses

lokaliseApi.translationStatuses.list({project_id: project_id});

Retrieve translation status

lokaliseApi.translationStatuses.get(status_id, {project_id: project_id});

Create translation status

lokaliseApi.translationStatuses.create(
    {title: 'my status', color: '#344563'},
    {project_id: project_id}
 );

Update translation status

lokaliseApi.translationStatuses.update(
    status_id,
    {title: 'my status updated', color: '#f2d600'},
    {project_id: project_id}
 );

Delete translation status

lokaliseApi.translationStatuses.delete(status_id, {project_id: project_id});

Retrieve available colors for translation statuses

lokaliseApi.translationStatuses.available_colors({project_id: project_id});

Webhooks

Documentation

List webhooks

lokaliseApi.webhooks.list({project_id: project_id});

Retrieve webhook

lokaliseApi.webhooks.get(webhook_id, {project_id: project_id});

Create webhook

lokaliseApi.webhooks.create(
  {url: 'https://example.com', events: ['project.exported']},
  {project_id: project_id}
);

Update webhook

lokaliseApi.webhooks.update(
  webhook_id,
  {url: 'http://example.com', events: ['project.snapshot']},
  {project_id: project_id}
);

Delete webhook

lokaliseApi.webhooks.delete(
  webhook_id,
  {project_id: project_id}
);

Regenerate webhook secret

lokaliseApi.webhooks.regenerate_secret(
  webhook_id,
  {project_id: project_id}
);

Additional Info

Error handling

To handle request errors, you may use the following approach:

lokaliseApi.projects.list().catch(
  (e) => {
    console.log(e);
  }
);

Error codes are listed in the API docs.

API Rate Limits

Lokalise does not rate-limit API requests, however retain a right to decline the service in case of excessive use. Only one concurrent request per token is allowed. To ensure data consistency, it is not recommended to access the same project simultaneously using multiple tokens.

Running Tests

This library is tested with Node 10+. To test it locally:

1. Copypaste .env.example file as .env. Put your API token inside. The .env file is excluded from version control so your token is safe. All in all, we use pre-recorded cassettes, so the actual API requests won't be sent. However, providing at least some token is required.
2. Run npm test. Observe test results and coverage.

Building

1. Run npm run-script build
2. Browse dist/ folder

License

This library is licensed under the BSD 3 Clause. Prior to version 5.1.0 the license was MIT.

Copyright (c) Lokalise group, Ilya Bodrov