Designed for Claude Code, also compatible with Codex and OpenClaw
Lokalise Core Workflow A
Overview
Primary workflow covering the "source to Lokalise" direction: upload translation files, create and update keys programmatically, tag keys for organization, and perform bulk operations. Both SDK and CLI approaches shown for every operation.
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
Source translation file(s) in a supported format (JSON, XLIFF, PO, YAML, etc.)
Instructions
Upload source translation files. File upload is async: the API returns a process object that must be polled until completion.
Tag keys for organization. Tags let you filter keys in the Lokalise UI and API — useful for release tracking, feature flags, and workflow status.
SDK — Add tags to existing keys (bulk):
// List keys by an existing tagconst v21Keys = await client.keys().list({
project_id: PROJECT_ID,
filter_tags: "v2.1",
limit: 500,
});
// Bulk-update: add a new tag to all of themconst keyIds = v21Keys.items.map((k) => k.key_id);
const updated = await client.keys().bulk_update({
project_id: PROJECT_ID,
keys: keyIds.map((id) => ({
key_id: id,
tags: ["v2.1", "ready-for-review"], // Full tag list (replaces existing)
})),
});
console.log(`Tagged ${updated.items.length} keys with 'ready-for-review'`);
SDK — Filter keys by tag:
const errorKeys = await client.keys().list({
project_id: PROJECT_ID,
filter_tags: "errors",
include_translations: 1,
limit: 100,
});
for (const k of errorKeys.items) {
const en = k.translations.find(
(t: { language_iso: string }) => t.language_iso === "en"
);
console.log(`${k.key_name.web}: ${en?.translation ?? "(empty)"}`);
}
Perform bulk key operations for large-scale changes.
SDK — Bulk delete keys:
// Delete keys that are no longer in the codebaseconst obsoleteKeys = await client.keys().list({
project_id: PROJECT_ID,
filter_tags: "deprecated",
limit: 500,
});
if (obsoleteKeys.items.length > 0) {
const deleteIds = obsoleteKeys.items.map((k) => k.key_id);
const result = await client.keys().bulk_delete(deleteIds, {
project_id: PROJECT_ID,
});
console.log(`Deleted ${result.keys_removed} keys`);
}
SDK — Bulk update translations:
// Mark all translations for a tag as "needs review" by clearing is_reviewedconst keysToReview = await client.keys().list({
project_id: PROJECT_ID,
filter_tags: "v2.2",
include_translations: 1,
limit: 500,
});
for (const key of keysToReview.items) {
for (const t of key.translations) {
if (t.is_reviewed) {
await client.translations().update(t.translation_id, {
project_id: PROJECT_ID,
is_reviewed: false,
});
}
}
}
CLI — Bulk operations:
set -euo pipefail
# Upload multiple files in sequence (respect rate limits)for lang in en fr de es ja; do
lokalise2 --token "$LOKALISE_API_TOKEN" file upload \
--project-id "$LOKALISE_PROJECT_ID" \
--file "./locales/${lang}.json" \
--lang-iso "$lang" \
--replace-modified \
--poll
echo"Uploaded ${lang}.json"sleep 1 # Rate limit bufferdone# Upload with cleanup mode (removes keys not present in file)
lokalise2 --token "$LOKALISE_API_TOKEN" file upload \
--project-id "$LOKALISE_PROJECT_ID" \
--file ./locales/en.json \
--lang-iso en \
--cleanup-mode \
--poll
Output
Source file uploaded to Lokalise with process confirmation
Keys created with descriptions, tags, and base translations
Keys organized by tags for filtering and workflow tracking
Bulk operations completed with count summaries
Error Handling
Error
Cause
Solution
400 Invalid file format
File extension or content not recognized
Verify format is in the supported formats list (see Resources)
400 Key already exists
Duplicate key_name + platform combo
Set replace_modified: true or use unique key names
413 Payload Too Large
Base64 payload exceeds 50MB
Split file or remove unused keys
429 Too Many Requests
Exceeded 6 req/sec
Add 170ms minimum delay between calls
Process status: failed
Invalid file content or encoding
Check file is valid JSON/XLIFF/PO and base64 encoding is correct
400 keys must be an array
Wrong payload shape for bulk ops
Wrap keys in an array even for single-key operations
Examples
CI Pipeline: Extract and Upload
// ci-upload.ts — extract keys from code and push to Lokaliseimport { LokaliseApi } from"@lokalise/node-api";
import { readFileSync } from"node:fs";
const client = newLokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });
constPROJECT_ID = process.env.LOKALISE_PROJECT_ID!;
// Upload the extracted source fileconst data = readFileSync("./locales/en.json").toString("base64");
const proc = await client.files().upload(PROJECT_ID, {
data,
filename: "en.json",
lang_iso: "en",
replace_modified: true,
cleanup_mode: true, // Remove keys not in this filetags: [`build-${process.env.CI_BUILD_NUMBER ?? "local"}`],
});
// Wait for completionlet status = proc.status;
while (status === "queued" || status === "running") {
awaitnewPromise((r) =>setTimeout(r, 2000));
const check = await client.queuedProcesses().get(proc.process_id, {
project_id: PROJECT_ID,
});
status = check.status;
}
if (status !== "finished") {
console.error(`Upload failed with status: ${status}`);
process.exit(1);
}
console.log("Source strings synced to Lokalise");
Tag-Based Release Workflow
set -euo pipefail
# Tag all untagged keys with the current release
lokalise2 --token "$LOKALISE_API_TOKEN" key list \
--project-id "$LOKALISE_PROJECT_ID" \
--filter-tags "" \
--limit 500 | jq -r '.[].key_id' | whileread -r key_id; do
lokalise2 --token "$LOKALISE_API_TOKEN" key update \
--project-id "$LOKALISE_PROJECT_ID" \
--key-id "$key_id" \
--tags "release-3.0"sleep 0.2
done
