Prerequisites

Your Node.js app must be prepared for localization (see Node.js i18n docs).
You'll need an existing Lokalise project. Specifically, you'll require the project ID that can be found in the project settings.
A read/write Lokalise API token is required. Learn how to work with the API tokens in the corresponding article.
The Lokalise CLI tool must be installed.
To run the Lokalise CLI tool from NodeJS, you will need to use the child_process.execFile API.

Using LokaliseFileExchange package

Use the lokalise-file-exchange to upload and download translation files. Check the sample app to see more examples.

Initial setup

Install the package:

npm install --save lokalise-file-exchange

Configure uploader and downloader:

import { LokaliseUpload, LokaliseDownload } from "lokalise-file-exchange";

const apiKey = "YOUR_API_TOKEN";
const projectId = "YOUR_PROJECT_ID";

const lokaliseUploader = new LokaliseUpload({apiKey}, {projectId});
const lokaliseDownloader = new LokaliseDownload({apiKey}, {projectId});

Learn more about client configuration in the package's readme. Now you're ready to perform file exchange!

Uploading to Lokalise

Prepare uploading options:

import type { CollectFileParams, ProcessUploadFileParams } from "lokalise-file-exchange";
import type { UploadFileParams } from "@lokalise/node-api";

const uploadFileParams: Partial<UploadFileParams> = {
  replace_modified: true, // Replace modified files on Lokalise
};

const collectFileParams: CollectFileParams = {
  inputDirs: ["./locales"],
  extensions: [".json"],
  // fileNamePattern: "^en\\.json$", // Regex to match only "en.json"
}

const processUploadFileParams: ProcessUploadFileParams = {
  pollStatuses: true, // Wait for file processing to complete on Lokalise
}

Note that most of these options are not mandatory. Learn more in the readme.

Start the upload:

const { processes, errors } = await lokaliseUploader.uploadTranslations({
  uploadFileParams,
  collectFileParams,
  processUploadFileParams,
});

processes will contain an array of queued processes. If the pollStatuses option has been set to true, the uploader will wait for all the processes to be completed or cancelled.

errors will contain an array of errors (if any).

Downloading from Lokalise

Prepare downloading options:

import type { DownloadFileParams } from "@lokalise/node-api";
import type { ExtractParams } from "lokalise-file-exchange";

const downloadFileParams: DownloadFileParams = {
  format: "json", // Format of downloaded translations
  original_filenames: true, // Keep original filenames from Lokalise
  indentation: "2sp", // Indentation style
  directory_prefix: "", // Directory structure prefix
};

const extractParams: ExtractParams = {
  outputDir: "./", // Target directory for extracted files
}

Note that most of these options are not mandatory. Learn more in the readme.

Start the download:

await lokaliseDownloader.downloadTranslations({
  downloadFileParams,
  extractParams,
});

Downloader will automatically expand the archive with your translations to the specified path. If no errors have been raised, it means the process has been completed successfully. Please note that existing translations will be overwritten.

Using Lokalise CLIv2

Use Lokalise command line tool to easily exchange translation files.

Uploading to Lokalise

Upload your translation files to Lokalise:

$ lokalise2 \
 --token <token> \
 --project-id <project_id> \
 file upload \
 --file "myapp/locales/en.json" \
 --lang-iso en

Additional upload options can be found in the CLI docs.

Downloading from Lokalise

As the translators are done you need to download the language files from Lokalise:

$ lokalise2 \
 --token <token> \
 --project-id <project_id> \
 file download \
 --format json \
 --original-filenames=false \
 --bundle-structure "%LANG_ISO%.json" \
 --unzip-to "myapp/locales/"

Additional download options can be found in the CLI docs.