Lokalise Upgrade Migration

What it does

When your agent uses it

• Upgrading Lokalise SDK versions
• Detecting deprecations
• Migrating to new API versions
• With phrases like upgrade lokalise

Example prompts

• “upgrade lokalise”
• “lokalise migration”
• “lokalise breaking changes”
• “/lokalise-upgrade-migration”

Requirements

• Node.js
• A credential in LOKALISE_API_TOKEN
• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(git:*), Bash(node:*), Bash(grep:*), Grep

Workflow steps

7 steps, taken from the step headings in SKILL.md.

1. 1Assess Current Version and Target
2. 2Review Breaking Changes by Version
3. 3Migrate Imports (v8 CJS to v9 ESM)
4. 4Update Pagination Code (v6/v7 to v9)
5. 5Update Error Handling
6. 6Install and Verify
7. 7Verify API Compatibility

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash(npm:*)
  • Bash(npx:*)
  • Bash(git:*)
  • Bash(node:*)
  • Bash(grep:*)
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • npm
  • node
  • git
  • curl
  • npx
  • brew

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • github.com
  • api.github.com

  Also links to:

  • lokalise.github.io
  • developers.lokalise.com
  • nodejs.org

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • LOKALISE_API_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Lokalise Upgrade Migration loads about 2.2k tokens when it runs, and up to ~3.5k if it reads all its reference files. Until then it costs about 89 tokens; SKILL.md has 444 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~89

When it runs · the whole SKILL.md, loaded when a task matches

~2.2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteRuns commands with sudoSKILL.md:251

  sudo mv lokalise2 /usr/local/bin/

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 444 words, ~2,239 tokens.

name

lokalise-upgrade-migration

description

Analyze, plan, and execute Lokalise SDK upgrades with breaking change detection. Use when upgrading Lokalise SDK versions, detecting deprecations, or migrating to new API versions. Trigger with phrases like "upgrade lokalise", "lokalise migration", "lokalise breaking changes", "update lokalise SDK", "analyze lokalise version".

allowed-tools

Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(git:*), Bash(node:*), Bash(grep:*), Grep

compatibility

Designed for Claude Code

version

1.14.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, lokalise, api, migration

set -euo pipefail
echo "=== Current SDK Version ==="
CURRENT=$(npm list @lokalise/node-api --json 2>/dev/null | node -e "
  const d = JSON.parse(require('fs').readFileSync(0,'utf8'));
  const v = d.dependencies?.['@lokalise/node-api']?.version || 'not found';
  console.log(v);
")
echo "Installed: ${CURRENT}"

echo -e "\n=== Latest Available ==="
LATEST=$(npm view @lokalise/node-api version)
echo "Latest: ${LATEST}"

echo -e "\n=== All Major Versions ==="
npm view @lokalise/node-api versions --json | node -e "
  const versions = JSON.parse(require('fs').readFileSync(0,'utf8'));
  const majors = {};
  versions.forEach(v => { const m = v.split('.')[0]; majors[m] = v; });
  Object.entries(majors).forEach(([m, v]) => console.log('  v' + m + '.x latest: ' + v));
"

set -euo pipefail
grep -rn "require.*lokalise\|from.*lokalise" --include="*.ts" --include="*.js" --include="*.mjs" . || echo "No imports found"

// BEFORE (v8 CommonJS)
const { LokaliseApi } = require('@lokalise/node-api');
const lok = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN });

// AFTER (v9 ESM)
import { LokaliseApi } from '@lokalise/node-api';
const lok = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN });

{
  "type": "module"
}

{
  "compilerOptions": {
    "module": "ES2022",
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

// BEFORE (v6 offset pagination)
const keys = await lok.keys().list({
  project_id: projectId,
  page: 2,
  limit: 100,
});

// AFTER (v9 cursor pagination — preferred for large datasets)
const keys = await lok.keys().list({
  project_id: projectId,
  limit: 500,
  pagination: 'cursor',
  cursor: previousCursor,
});
// Access next cursor: keys.nextCursor
// Check for more: keys.hasNextCursor()

// BEFORE (v8)
const { ApiError } = require('@lokalise/node-api');
try {
  await lok.projects().get(projectId);
} catch (e) {
  if (e instanceof ApiError) {
    console.error(e.message, e.code);
  }
}

// AFTER (v9 — ApiError import path unchanged, but must use import)
import { ApiError } from '@lokalise/node-api';
try {
  await lok.projects().get(projectId);
} catch (e) {
  if (e instanceof ApiError) {
    console.error(e.message, e.code);
  }
}

set -euo pipefail
# Create a safety branch
git checkout -b upgrade/lokalise-sdk-v9

# Install the target version
npm install @lokalise/node-api@latest

# Run TypeScript compilation check
npx tsc --noEmit 2>&1 | head -40 || true

# Run tests
npm test

// Quick smoke test after upgrade
import { LokaliseApi } from '@lokalise/node-api';

const lok = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

// Test basic operations still work
const projects = await lok.projects().list({ limit: 1 });
console.log('API connection OK:', projects.items[0]?.name ?? 'no projects');

const keys = await lok.keys().list({
  project_id: projects.items[0].project_id,
  limit: 5,
  pagination: 'cursor',
});
console.log('Cursor pagination OK:', keys.items.length, 'keys fetched');

set -euo pipefail
# If the upgrade causes issues, revert immediately
git stash  # Save any work in progress
npm install @lokalise/node-api@8  # Last CJS version
git checkout HEAD -- tsconfig.json package.json
npm test
echo "Rolled back to v8. Investigate failures before retrying."

set -euo pipefail
# macOS
brew upgrade lokalise2

# Linux — download latest release binary
LATEST_CLI=$(curl -s https://api.github.com/repos/lokalise/lokalise-cli-2-go/releases/latest | grep -oP '"tag_name": "\K[^"]+')
curl -sL "https://github.com/lokalise/lokalise-cli-2-go/releases/download/${LATEST_CLI}/lokalise2_linux_x86_64.tar.gz" | tar xz
sudo mv lokalise2 /usr/local/bin/

# Verify
lokalise2 --version

set -euo pipefail
# Patterns that indicate outdated SDK usage
echo "=== Deprecated Patterns ==="
grep -rn "\.page\s*:" --include="*.ts" --include="*.js" . && echo "^ Offset pagination — migrate to cursor" || echo "No offset pagination found"
grep -rn "require.*lokalise" --include="*.ts" --include="*.js" . && echo "^ CommonJS require — migrate to ESM import" || echo "No CJS requires found"
grep -rn "new LokaliseApi.*token:" --include="*.ts" --include="*.js" . && echo "^ Old constructor — use apiKey instead of token" || echo "No old constructor pattern found"

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in skills/.curated/lokalise-upgrade-migration of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/implementation-guide.md

Open the folder on GitHubat commit cfae287