bfricka / node-lokalise-api

Lokalise API v2 Node.js client.

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 not 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 MIT License.

Copyright (c) Lokalise team, Roman Kutanov, Ilya Bodrov