lokalise-core-workflow-a — Claude Code skill for pushing keys to Lokalise
lokalise-core-workflow-a — a Claude Code skill for the source-to-Lokalise direction: uploading translation files, creating and editing keys. Also runs in Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.
MIT 1 installs ★ 2,935 updated 2026-11-01
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a claude-codeWhat lokalise-core-workflow-a does
The skill handles uploads, key creation with initial translations, tag management, and bulk operations. Every task in the instructions appears twice: as TypeScript using @lokalise/node-api and as a lokalise2 CLI command, so the agent can pick whichever fits the project.
File upload is async. The API hands back a process object and the skill polls it until it reaches finished. The CLI route has a --poll flag for this, the SDK route includes a wait loop that throws on cancelled or failed processes. Keys get tagged during upload or later through bulk_update, which replaces the full tag list.
The skill needs LOKALISE_API_TOKEN and LOKALISE_PROJECT_ID set in the environment. Without both, the agent cannot reach the project. Source files in JSON, XLIFF, PO, or YAML all work.
What it helps with
- upload a translation file to a Lokalise project
- create keys with initial English translations
- tag a group of keys for a release
- bulk-delete keys no longer present in the code
- update descriptions and hidden flags on existing keys
Example prompts for the agent
- Upload ./locales/en.json to the Lokalise project and tag it source and v2.1
- Create onboarding.step1.title and onboarding.step1.body with English translations
- Find all keys tagged v2.1 and add ready-for-review to them
How to install lokalise-core-workflow-a
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a claude-code2Manually: put the files in place
~/.claude/skills/lokalise-core-workflow-a/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/lokalise-core-workflow-a/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a codex2Manually: put the files in place
.agents/skills/lokalise-core-workflow-a/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a cursor2Manually: put the files in place
.cursor/skills/lokalise-core-workflow-a/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jeremylongshore/tons-of-skills-marketplace skills/.curated/lokalise-core-workflow-a2Manually: put the files in place
.github/skills/lokalise-core-workflow-a/SKILL.md1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a gemini-cli2Platform CLI
gemini skills install https://github.com/jeremylongshore/tons-of-skills-marketplace --path skills/.curated/lokalise-core-workflow-aManually: put the files in place
.devin/skills/lokalise-core-workflow-a/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about lokalise-core-workflow-a
How do I install lokalise-core-workflow-a in Claude Code?
Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill lokalise-core-workflow-a -a claude-code. The skill lands in ~/.claude/skills/lokalise-core-workflow-a/SKILL.md.
What does lokalise-core-workflow-a do?
It covers the source-to-Lokalise workflow: uploading files, creating and updating keys, applying tags, and bulk operations. Each task is documented for both SDK and CLI.
What do I need before using it?
A Lokalise API token in LOKALISE_API_TOKEN and the project ID in LOKALISE_PROJECT_ID. SDK examples need @lokalise/node-api, CLI examples need lokalise2 installed.
Source text
SKILL.md · MIT
--- name: lokalise-core-workflow-a description: 'Execute Lokalise primary workflow: Upload source files and manage translation keys. Use when uploading translation files, creating/updating keys, or managing source strings in Lokalise projects. Trigger with phrases like "lokalise upload", "lokalise push keys", "lokalise source strings", "add translations to lokalise". ' allowed-tools: Read, Write, Edit, Bash(lokalise2:*), Bash(npm:*), Grep version: 1.14.0 license: MIT author: Jeremy Longshore <[email protected]> tags: - saas - lokalise - workflow compatibility: Designed for Claude Code --- # 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 1. Upload source translation files. File upload is async: the API returns a process object that must be polled until completion. **SDK — Base64 encode and upload:** ```typescript import { LokaliseApi } from "@lokalise/node-api"; import { readFileSync } from "node:fs"; const client = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! }); const PROJECT_ID = process.env.LOKALISE_PROJECT_ID!; // Read and base64-encode the source file const fileContent = readFileSync("./locales/en.json"); const base64Data = fileContent.toString("base64"); const uploadProcess = await client.files().upload(PROJECT_ID, { data: base64Data, filename: "en.json", lang_iso: "en", replace_modified: true, // Overwrite changed translations distinguish_by_file: true, // Same key names in different files stay separate tags: ["source", "v2.1"], // Auto-tag uploaded keys }); console.log(`Upload queued: process ${uploadProcess.process_id}, status: ${uploadProcess.status}`); ``` **SDK — Poll upload process until complete:** ```typescript async function waitForUpload( client: LokaliseApi, projectId: string, processId: string, maxWaitMs = 60_000 ): Promise<void> { const start = Date.now(); while (Date.now() - start < maxWaitMs) { const proc = await client.queuedProcesses().get(processId, { project_id: projectId }); console.log(` Process ${processId}: ${proc.status}`); if (proc.status === "finished") return; if (proc.status === "cancelled" || proc.status === "failed") { throw new Error(`Upload ${proc.status}: ${JSON.stringify(proc.details)}`); } await new Promise((r) => setTimeout(r, 1000)); } throw new Error(`Upload timed out after ${maxWaitMs}ms`); } await waitForUpload(client, PROJECT_ID, uploadProcess.process_id); console.log("Upload complete"); ``` **CLI — Upload with polling:** ```bash set -euo pipefail lokalise2 --token "$LOKALISE_API_TOKEN" file upload \ --project-id "$LOKALISE_PROJECT_ID" \ --file ./locales/en.json \ --lang-iso en \ --replace-modified \ --distinguish-by-file \ --tag-inserted-keys \ --tag-updated-keys \ --tags "source,v2.1" \ --poll # Waits for process to finish ``` 1. Create keys programmatically when keys come from code scanning, CMS exports, or CI pipelines rather than file uploads. **SDK — Create keys with initial translations:** ```typescript const newKeys = await client.keys().create({ project_id: PROJECT_ID, keys: [ { key_name: { web: "onboarding.step1.title" }, platforms: ["web"], description: "First step of onboarding wizard", tags: ["onboarding", "v2.1"], translations: [ { language_iso: "en", translation: "Welcome aboard!" }, ], }, { key_name: { web: "onboarding.step1.body" }, platforms: ["web"], description: "Body text for onboarding step 1", tags: ["onboarding", "v2.1"], translations: [ { language_iso: "en", translation: "Let's get you set up in just a few steps." }, ], }, { key_name: { web: "errors.network_timeout" }, platforms: ["web"], description: "Shown when API call times out", is_hidden: false, tags: ["errors"], translations: [ { language_iso: "en", translation: "Connection timed out. Please try again." }, ], }, ], }); console.log(`Created ${newKeys.items.length} keys`); for (const k of newKeys.items) { console.log(` ${k.key_id}: ${k.key_name.web}`); } ``` **SDK — Update existing keys:** ```typescript const updatedKey = await client.keys().update(KEY_ID, { project_id: PROJECT_ID, description: "Updated description", tags: ["onboarding", "v2.2", "reviewed"], is_hidden: false, }); ``` 1. 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):** ```typescript // List keys by an existing tag const v21Keys = await client.keys().list({ project_id: PROJECT_ID, filter_tags: "v2.1", limit: 500, }); // Bulk-update: add a new tag to all of them const 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:** ```typescript 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)"}`); } ``` 1. Perform bulk key operations for large-scale changes. **SDK — Bulk delete keys:** ```typescript // Delete keys that are no longer in the codebase const 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:** ```typescript // Mark all translations for a tag as "needs review" by clearing is_reviewed const 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:** ```bash 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 buffer done # 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 ```typescript // ci-upload.ts — extract keys from code and push to Lokalise import { LokaliseApi } from "@lokalise/node-api"; import { readFileSync } from "node:fs"; const client = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! }); const PROJECT_ID = process.env.LOKALISE_PROJECT_ID!; // Upload the extracted source file const 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 file tags: [`build-${process.env.CI_BUILD_NUMBER ?? "local"}`], }); // Wait for completion let status = proc.status; while (status === "queued" || status === "running") { await new Promise((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 ```bash 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' | while read -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 ``` ## Resources - [File Upload API](https://developers.lokalise.com/reference/upload-a-file) - [Queued Processes](https://developers.lokalise.com/reference/list-all-processes) - [Keys API — Create](https://developers.lokalise.com/reference/create-keys) - [Keys API — Bulk Update](https://developers.lokalise.com/reference/bulk-update) - [Keys API — Bulk Delete](https://developers.lokalise.com/reference/delete-multiple-keys) - [Supported File Formats](https://docs.lokalise.com/en/articles/1400492-uploading-translation-files) ## Next Steps For downloading translations and managing contributors, see `lokalise-core-workflow-b`.
© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace