Execute Lokalise secondary workflow: Download translations and integrate with app.
Use when downloading translation files, exporting translations,
or integrating Lokalise output into your application.
Trigger with phrases like "lokalise download", "lokalise pull translations",
"export lokalise", "get translations from lokalise".
Everything on the "Lokalise to app" side: download translated files, manage translations and review status, leverage translation memory, manage contributors and their language access, and handle format differences across JSON, XLIFF, and PO files.
Prerequisites
Lokalise API token exported as LOKALISE_API_TOKEN
Lokalise project ID exported as LOKALISE_PROJECT_ID
@lokalise/node-api installed for SDK examples
lokalise2 CLI installed for CLI examples
unzip available for extracting download bundles
Instructions
Download translated files. The download endpoint returns an S3 URL to a zip bundle — request the bundle, download the zip, then extract.
SDK — Download and extract:
import { LokaliseApi } from "@lokalise/node-api";
import { execSync } from "node:child_process";
import { mkdirSync } from "node:fs";
const client = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });
const PROJECT_ID = process.env.LOKALISE_PROJECT_ID!;
// Request the download bundle
const download = await client.files().download(PROJECT_ID, {
format: "json",
original_filenames: false,
bundle_structure: "%LANG_ISO%.json", // Output: en.json, fr.json, de.json
filter_langs: ["en", "fr", "de", "es"], // Only these languages
export_empty_as: "base", // Use base language for empty translations
include_tags: ["release-3.0"], // Only keys with this tag
replace_breaks: false,
});
const bundleUrl = download.bundle_url;
console.log(`Bundle URL: ${bundleUrl}`);
// Download and extract
mkdirSync("./locales", { recursive: true });
execSync(`curl -sL "${bundleUrl}" -o /tmp/lokalise-bundle.zip`);
execSync(`unzip -o /tmp/lokalise-bundle.zip -d ./locales`);
console.log("Translations extracted to ./locales/");
Manage translations — list, update, and mark as reviewed.
SDK — List translations for a language:
const frTranslations = await client.translations().list({
project_id: PROJECT_ID,
filter_lang_id: 673, // Language ID for French (find via languages endpoint)
filter_is_reviewed: 0, // Only unreviewed
limit: 100,
});
for (const t of frTranslations.items) {
console.log(`[${t.key_id}] ${t.translation} (reviewed: ${t.is_reviewed})`);
}
SDK — Update a translation:
const updated = await client.translations().update(TRANSLATION_ID, {
project_id: PROJECT_ID,
translation: "Nouvelle traduction",
is_reviewed: false, // Mark as needing review after edit
});
SDK — Mark translations as reviewed (batch):
const unreviewed = await client.translations().list({
project_id: PROJECT_ID,
filter_lang_id: LANG_ID,
filter_is_reviewed: 0,
limit: 500,
});
for (const t of unreviewed.items) {
await client.translations().update(t.translation_id, {
project_id: PROJECT_ID,
is_reviewed: true,
});
}
console.log(`Marked ${unreviewed.items.length} translations as reviewed`);
SDK — List translations with cursor pagination (for large datasets):
async function* paginateTranslations(
client: LokaliseApi,
projectId: string,
langId: number
) {
let cursor: string | undefined;
do {
const params: Record<string, unknown> = {
project_id: projectId,
filter_lang_id: langId,
limit: 500,
};
if (cursor) params.cursor = cursor;
const page = await client.translations().list(params);
yield* page.items;
cursor = page.hasNextCursor() ? page.nextCursor() : undefined;
} while (cursor);
}
// Usage
for await (const t of paginateTranslations(client, PROJECT_ID, 673)) {
console.log(`${t.key_id}: ${t.translation}`);
}
Leverage translation memory (TM) for auto-suggestions based on previously translated segments.
SDK — Leverage TM during download (pre-translate empty keys):
// Pre-translate uses TM + MT before download
// First, trigger pre-translation
// Then download with filled translations
const download = await client.files().download(PROJECT_ID, {
format: "json",
original_filenames: false,
bundle_structure: "%LANG_ISO%.json",
export_empty_as: "base", // Fallback to base language if TM has no match
});
Manage contributors — add translators and configure language access.
SDK — Add a translator with specific language access:
// Lokalise detects format from filename extension
// Just make sure the filename matches the content format
await client.files().upload(PROJECT_ID, {
data: base64Data,
filename: "messages.xliff", // Triggers XLIFF parser
lang_iso: "en",
});
Output
Downloaded translation files extracted to project directory
Translations updated and review status managed
Contributors added with appropriate language permissions
Files exported in the correct format for your i18n framework
