Exchange translation files with Lokalise TMS
npm install lokalise-file-exchangebash
npm install --save lokalise-file-exchange
`
$3
Use the LokaliseUpload class to upload translation files from your project to Lokalise:
`js
import { LokaliseUpload } from "lokalise-file-exchange";
const apiKey = "YOUR_LOKALISE_API_TOKEN";
const projectId = "YOUR_LOKALISE_PROJECT_ID";
const lokaliseUploader = new LokaliseUpload(
{
apiKey,
},
{
projectId,
},
);
// Upload all files from the ./locales directory:
const { processes, errors } = await lokaliseUploader.uploadTranslations();
console.log(processes); // Array of QueuedProcess objects
console.log(errors); // Array of errors (if any)
`
$3
Use the LokaliseDownload class to download translation files from Lokalise into your project:
`js
import { LokaliseDownload } from "lokalise-file-exchange";
import type { DownloadFileParams } from "@lokalise/node-api";
const apiKey = "YOUR_LOKALISE_API_TOKEN";
const projectId = "YOUR_LOKALISE_PROJECT_ID";
const lokaliseDownloader = new LokaliseDownload(
{
apiKey,
},
{
projectId,
},
);
const downloadFileParams: DownloadFileParams = {
// Format is mandatory!
format: "json", // Output format for the downloaded files
// Other params are optional
original_filenames: true, // Preserve original filenames from Lokalise
indentation: "2sp", // Indentation style for the downloaded files
directory_prefix: "", // Optional prefix for output directory structure
};
// Download all translations into the project root while preserving original filenames
await lokaliseDownloader.downloadTranslations({ downloadFileParams });
`
Creating and configuring client
The first step is to create an upload or download client. Both clients accept two configuration objects.
`js
import { LokaliseUpload } from "lokalise-file-exchange";
// OR
import { LokaliseDownload } from "lokalise-file-exchange";
const lokaliseUploader = new LokaliseUpload({ apiKey }, { projectId });
// OR
const lokaliseDownloader = new LokaliseDownload({ apiKey }, { projectId });
`
If you're using OAuth2 flow, set useOAuth2 option to true:
`js
const lokaliseUploader = new LokaliseUpload(
{ apiKey },
{ projectId, useOAuth2: true },
);
// OR
const lokaliseDownloader = new LokaliseDownload(
{ apiKey },
{ projectId, useOAuth2: true },
);
`
In this case make sure to provide access token for the apiKey.
$3
The first object is ClientParams, used to instantiate the node-lokalise-api client internally for sending API requests. The only mandatory parameter is apiKey, which should contain a string with your Lokalise API token. Other parameters are optional and can be used to:
- Configure timeouts and API host
- Enable compression
- Customize other client options
LokaliseExchangeConfig configuration
The second object, LokaliseExchangeConfig, contains additional parameters:
- projectId (string, required): Your Lokalise project ID. If you're using project branching, provide the branch name after semicolon, for example "123.abc:my_branch".
- retryParams (RetryParams, optional): Retry parameters for failed API requests. By default, the library performs up to 3 retries for 408 (timeout) and 429 (too many requests) errors. Exponential backoff is applied, with an initial sleep time of 1000 ms. Parameters include:
- maxRetries (number): Maximum number of retries. If set to 0, the client will send only a single request without any retries.
- initialSleepTime (number): The initial value for the sleep time in milliseconds. Subsequent sleep times are calculated using the formula initialSleepTime 2 * (attempt - 1), where attempt > 0.
- logThreshold: Controls the minimum severity level required for a message to be logged. Possible values: "debug", "info", "warn", "error", "silent". Messages below this threshold are ignored — for example, setting it to "warn" will hide all debug and info logs. Default is "info".
- logColor (boolean): Whether to use colored output when printing messages to console. Default is true.
Performing translation file downloads
To download translation files from Lokalise into your project, use the downloadTranslations() method on the client.
`js
await lokaliseDownloader.downloadTranslations({
downloadFileParams,
extractParams,
processDownloadFileParams,
});
`
downloadTranslations() accepts a single object, DownloadTranslationParams, with three attributes.
$3
The DownloadFileParams attribute contains all download parameters passed directly to the download() function. For details about supported parameters, refer to the DownloadFiles endpoint documentation.
Required parameter:
- format (string): Specifies the download format (e.g., json, xml, etc.).
$3
After downloading the translation bundle, the client extracts it automatically. You can control the extraction process with the following parameter:
- outputDir (string, optional): Specifies the directory where the archive is extracted. The default value is "./" (project root).
$3
By default, all downloads are performed synchronously. However, for larger projects it might be beneficial to use asynchronous downloading. To achieve that, configure processDownloadFileParams that accepts:
- asyncDownload (boolean): Enable or disable asynchronous downloads. The default value is false.
- pollInitialWaitTime (number): Initial wait time (in milliseconds) before polling download statuses.
- pollMaximumWaitTime (number): Maximum wait time (in milliseconds) for polling.
- bundleDownloadTimeout (number): Maximum time (in milliseconds) to wait for the translation bundle download to complete before aborting. The default value is undefined (no timeout).
When asynchronous download is enabled, library will try to poll for the download process status. Once the bundle is available, your translations will be automatically extracted.
Recommendations for downloading
To preserve original filenames assigned to translation keys during the download, use configurations that align with your project structure. For example:
- If your translations are located in a ./locales directory
- Keys have filenames assigned in the format locales/%LANG_ISO%.json or locales/some_nested_dir/%LANG_ISO%.json
`js
import type { DownloadFileParams } from "@lokalise/node-api";
import type { ExtractParams } from "lokalise-file-exchange";
const downloadFileParams: DownloadFileParams = {
format: "json",
original_filenames: true,
directory_prefix: "",
};
try {
await lokaliseDownloader.downloadTranslations({ downloadFileParams });
} catch (err) {
console.error(err);
}
`
You can configure your download to maintain this structure by specifying original_filenames and directory_prefix.
Performing translation file uploads
To upload translation files from Lokalise into your project, use the uploadTranslations() method.
`js
const { processes, errors } = await lokaliseUploader.uploadTranslations({
uploadFileParams,
collectFileParams,
processUploadFileParams,
});
`
File uploading happens in the background so this method will return an array of QueuedProcesses and an array of errors that happened during uploading.
This method accepts an optional UploadTranslationParams object for further customization. It consists of three main attributes.
$3
This attribute contains parameters passed to the upload() function. For details, refer to the UploadFile endpoint documentation.
The client automatically provides the following required parameters:
- data
- filename
- lang_iso
You do not need to set these manually.
$3
This attribute determines which files are included or excluded from the upload. All parameters are optional.
- inputDirs (string[]): Directories to upload translations from. Default: ["./locales"].
- extensions (string[]): File extensions to include. Default: [".*"] (all extensions). For example, set to [".json", ".xml"] to include only JSON and XML files.
- excludePatterns (string[] | RegExp[]): Patterns to exclude. Each item must be a valid regular expression string or a RegExp object. Patterns are tested against the full absolute path of each file or directory.
- recursive (boolean): Whether to include files from nested directories. Default: true.
- fileNamePattern (string | RegExp): Pattern for filenames to upload. Default: (all files). For example, set to "^en." to upload files starting with "en.".
$3
This attribute provides advanced configuration for the upload process.
- languageInferer: A function to infer the language ISO code for uploaded files.
- filenameInferer: A function to infer the filename for uploaded files.
- pollStatuses (boolean): Whether to wait for Lokalise to process the uploaded files. Default: false.
- pollInitialWaitTime (number): Initial wait time (in milliseconds) before polling upload statuses.
- pollMaximumWaitTime (number): Maximum wait time (in milliseconds) for polling.
#### Inferring language ISO code
Lokalise requires a lang_iso parameter for every file. By default, the client infers this from the filename (e.g., en.json > lang_iso: "en", main.fr_FR.xml > lang_iso: "fr_FR"). If the project lacks the corresponding language, the upload fails.
For custom logic, use the languageInferer function, which has the signature:
(filePath: string) => Promise. If this function fails or returns an empty string, the filename is used as a language ISO code.
Example: Inferring from file content
Suppose the file's first key contains the language code:
`json
{
"en": {
"key": "translation value"
}
}
`
You can infer the language with:
`js
const { processes, errors } = await lokaliseUpload.uploadTranslations({
processUploadFileParams: {
languageInferer: async (filePath) => {
// Provide any conditions as needed
if (path.extname(filePath) === ".json") {
const fileData = await fs.promises.readFile(filePath);
const jsonContent = JSON.parse(fileData.toString());
return Object.keys(jsonContent)[0];
}
return "";
},
},
});
`
Example: Inferring from parent folder
If translation files are stored in language-named folders (/locales/en/main.json), use:
`js
const { processes, errors } = await lokaliseUploader.uploadTranslations({
processUploadFileParams: {
languageInferer: (filePath) => {
try {
const parentDir = path.dirname(filePath);
return path.basename(parentDir);
} catch (_error) {
return "";
}
},
},
});
`
#### Inferring filename
Lokalise requires a filename parameter for every file. By default, the client infers this from the file path relative to the project root.
For custom logic, use the filenameInferer function, which has the signature:
(filePath: string) => Promise.
#### Polling for upload statuses
All translation files are uploaded to Lokalise in the background, which is why the uploadTranslations() method returns an array of processes containing QueuedProcess[] objects. By default, the client does not wait for Lokalise to complete the upload process or report the success or failure of each file.
To ensure the client waits until all files are fully processed by Lokalise, you can set the pollStatuses option to true. This enables the client to poll the status of each file until it is marked as completed, cancelled, or failed. Additionally, you can fine-tune the polling behavior by configuring the pollInitialWaitTime (initial wait time before polling starts) and pollMaximumWaitTime (maximum duration to wait for all uploads to be processed).
`js
const { processes, errors } = await lokaliseUploader.uploadTranslations({
processUploadFileParams: {
pollStatuses: true,
pollInitialWaitTime: 2e3,
pollMaximumWaitTime: 150e3,
},
});
``