lokalise-upgrade-migration

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
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","lokalise","api","migration"]
compatibility	Designed for Claude Code

Lokalise Upgrade Migration

Current State

!npm list @lokalise/node-api 2>/dev/null | grep lokalise || echo 'SDK not installed' !lokalise2 --version 2>/dev/null || echo 'CLI not installed' !node --version 2>/dev/null || echo 'Node.js not available' !cat package.json 2>/dev/null | grep -E '"type"|"module"' || echo 'No package.json type field'

Overview

Upgrade the @lokalise/node-api SDK between major versions with full breaking change detection, automated code transformation, and verification. The most significant migration is v8 (CommonJS) to v9+ (ESM-only), which requires changes to imports, module configuration, and potentially your build pipeline.

Prerequisites

• Existing project using @lokalise/node-api (any version 6.x through 9.x)
• Node.js 18+ for SDK v9 (Node.js 14+ for v8 and below)
• Git repository with clean working tree (for safe rollback)
• Test suite that exercises Lokalise API calls

Instructions

Step 1: Assess Current Version and Target

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));
"

Step 2: Review Breaking Changes by Version

Version	Node.js	Module System