lokalise-migration-deep-dive

name	lokalise-migration-deep-dive
description	Execute major migration to Lokalise from other TMS platforms with data migration strategies. Use when migrating to Lokalise from competitors, performing data imports, or re-platforming existing translation management to Lokalise. Trigger with phrases like "migrate to lokalise", "lokalise migration", "switch to lokalise", "lokalise import", "lokalise replatform".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(lokalise2:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Lokalise Migration Deep Dive

Overview

Comprehensive guide for migrating to Lokalise from other TMS platforms or legacy systems.

Prerequisites

• Access to source system for export
• Lokalise account with appropriate plan
• Understanding of current translation workflow
• Rollback strategy defined

Migration Types

Type	Complexity	Duration	Risk
Fresh start	Low	Days	Low
From Phrase	Medium	1-2 weeks	Medium
From Crowdin	Medium	1-2 weeks	Medium
From POEditor	Low	Days	Low
From spreadsheets	Medium	1 week	Medium
Custom legacy	High	2-4 weeks	High

Instructions

Step 1: Pre-Migration Assessment

interface MigrationAssessment {
  sourceSystem: string;
  totalProjects: number;
  totalKeys: number;
  totalLanguages: number;
  translationMemory: boolean;
  glossary: boolean;
  screenshots: boolean;
  workflows: boolean;
  integrations: string[];
  customizations: string[];
}

async function assessCurrentState(): Promise<MigrationAssessment> {
  // Document current system
  return {
    sourceSystem: "phrase",  // or crowdin, poeditor, etc.
    totalProjects: 5,
    totalKeys: 15000,
    totalLanguages: 12,
    translationMemory: true,
    glossary: true,
    screenshots: true,
    workflows: true,
    integrations: ["github", "figma", "slack"],
    customizations: ["custom placeholders", ],
  };
}


 (): {
  :  |  | ;
  : ;
  : [];
} {
   baseEffort = assessment. >  ?  : ;
   tmEffort = assessment. ?  : ;
   integrationEffort = assessment.. * ;

   totalDays = baseEffort + tmEffort + integrationEffort;

   {
    : totalDays >  ?  : totalDays >  ?  : ,
    : .(totalDays),
    : [
      assessment. >  ?  : ,
      assessment. ?  : ,
      assessment. ?  : ,
    ].()  [],
  };
}

Step 2: Export from Source System

# Export from common platforms

# Phrase
phrase pull --format json --target ./export/phrase/

# Crowdin (using CLI)
crowdin download --all --export-only-approved

# POEditor
# Use web export or API to download all languages

# Generic: Export all files in JSON/XLIFF format
# Ensure consistent naming: en.json, es.json, fr.json, etc.

Step 3: Data Transformation

// Transform exported data to Lokalise-compatible format
interface SourceKey {
  key: string;
  value: string;
  description?: string;
  tags?: string[];
  context?: string;
}

interface LokaliseImportKey {
  key_name: string;
  platforms: string[];
  description?: string;
  tags?: string[];
  translations: Array<{
    language_iso: string;
    translation: string;
  }>;
}

function transformKeys(
  sourceKeys: SourceKey[],
  translations: Record<string, Record<string, string>>,
  languages: string[]
): LokaliseImportKey[] {
  return sourceKeys.map(src => ({
    key_name: src.key,
    platforms: ["web"],  // Adjust based on your needs
    description: src. || src.,
    : src. || [],
    : languages.( ({
      : lang,
      : translations[lang]?.[src.] || ,
    })).( t.),
  }));
}


 ():  {
   (sourceSystem) {
     :
      
       key;
     :
      
       key.(, );
     :
      
       key.(, ).();
    :
       key;
  }
}

Step 4: Create Lokalise Project

import { LokaliseApi } from "@lokalise/node-api";

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

async function createMigrationProject(
  name: string,
  languages: string[],
  baseLanguage: string
): Promise<string> {
  const project = await client.projects().create({
    name: `${name} (Migration)`,
    description: `Migrated from legacy system on ${new Date().toISOString()}`,
    languages: languages.map(lang => ({
      lang_iso: lang,
    })),
    base_lang_iso: baseLanguage,
  });

  console.log(`Created project: ${project.project_id}`);
  return project.project_id;
}

Step 5: Import Keys and Translations

async function importKeysToLokalise(
  projectId: string,
  keys: LokaliseImportKey[],
  batchSize = 100
): Promise<{ imported: number; errors: string[] }> {
  const results = { imported: 0, errors: [] as string[] };

  for (let i = 0; i < keys.length; i += batchSize) {
    const batch = keys.slice(i, i + batchSize);

    try {
      const response = await client.keys().create({
        project_id: projectId,
        keys: batch,
      });

      results.imported += response.items.length;
      console.log(`Imported ${results.imported}/${keys.length} keys`);
    } catch (error: any) {
      results.errors.push(`Batch ${i / batchSize}: ${error.message}`);
      console.error(, error.);
    }

    
      ( (r, ));
  }

   results;
}


  (): <> {
   fileContent = fs.(filePath);
   base64Content = fileContent.();

   process =  client.().(projectId, {
    : base64Content,
    : path.(filePath),
    : langIso,
    : ,
    : ,
    : ,  
    : [],
  });

  .();

  
   (projectId, process.);
}

Step 6: Migrate Translation Memory

// Lokalise supports TM import via TMX format
async function importTranslationMemory(
  teamId: number,
  tmxFilePath: string
): Promise<void> {
  // Read TMX file
  const tmxContent = fs.readFileSync(tmxFilePath);
  const base64Content = tmxContent.toString("base64");

  // Upload to team TM
  await client.translationStatuses().create(teamId, {
    // TM import endpoint - check Lokalise API for exact parameters
  });

  console.log("Translation memory imported");
}

// Export TM from source system first
// Phrase: phrase tm:download --format tmx
// Crowdin: Use web export

Step 7: Post-Migration Validation

interface ValidationResult {
  passed: boolean;
  checks: Array<{
    name: string;
    passed: boolean;
    details: string;
  }>;
}

async function validateMigration(
  projectId: string,
  expectedKeys: number,
  expectedLanguages: string[]
): Promise<ValidationResult> {
  const checks: ValidationResult["checks"] = [];

  // Check key count
  const keys = await client.keys().list({
    project_id: projectId,
    limit: 1,
  });
  const keyCountMatch = keys.total_count >= expectedKeys * 0.95;  // 95% threshold
  checks.push({
    name: "Key count",
    passed: keyCountMatch,
    details: `Found ${keys.total_count}, expected ~${expectedKeys}`,
  });

  // Check languages
  const languages = await client.().({ : projectId });
   langCodes = languages..( l.);
   languagesMatch = expectedLanguages.( langCodes.(l));
  checks.({
    : ,
    : languagesMatch,
    : ,
  });

  
   ( lang  expectedLanguages.( l !== )) {
     langData = languages..( l. === lang);
     coverage = langData?.?. ?? ;
    checks.({
      : ,
      : coverage > ,
      : ,
    });
  }

   {
    : checks.( c.),
    checks,
  };
}

Output

• Migration assessment complete
• Data exported and transformed
• Lokalise project created
• Keys and translations imported
• Migration validated

Error Handling

Issue	Cause	Solution
Key name conflicts	Different naming conventions	Normalize keys before import
Missing translations	Export incomplete	Re-export from source
Encoding issues	Non-UTF8 files	Convert to UTF-8
Rate limit during import	Too fast	Increase delays between batches
Placeholder mismatch	Different syntax	Transform placeholders

Examples

Placeholder Transformation

// Convert placeholders between formats
function convertPlaceholders(
  text: string,
  fromFormat: "printf" | "icu" | "curly",
  toFormat: "icu"
): string {
  if (fromFormat === "printf") {
    // %s, %d, %1$s -> {0}, {1}, etc.
    let index = 0;
    return text.replace(/%(\d+\$)?[sd]/g, () => `{${index++}}`);
  }

  if (fromFormat === "curly") {
    // {{name}} -> {name}
    return text.replace(/\{\{(\w+)\}\}/g, "{$1}");
  }

  return text;
}

Migration Rollback

#!/bin/bash
# rollback-migration.sh

# If migration fails, delete the new project
lokalise2 --token "$LOKALISE_API_TOKEN" \
  project delete --project-id "$NEW_PROJECT_ID"

# Keep using old system
echo "Migration rolled back. Continue using source system."

Full Migration Script

async function runMigration() {
  console.log("=== Lokalise Migration ===\n");

  // 1. Assess
  const assessment = await assessCurrentState();
  const estimate = estimateMigrationEffort(assessment);
  console.log(`Estimated effort: ${estimate.effort} (~${estimate.estimatedDays} days)`);

  // 2. Create project
  const projectId = await createMigrationProject(
    "My App",
    ["en", "es", "fr", "de"],
    "en"
  );

  // 3. Import keys
  const keys = await loadTransformedKeys("./export/");
  const importResult = await importKeysToLokalise(projectId, keys);
  console.log(`Imported ${importResult.imported} keys`);

  // 4. Validate
  const validation = await validateMigration(projectId, keys.length, ["en", "es", "fr", "de"]);

   (validation.) {
    .();
  }  {
    .();
    validation..( !c.).( {
      .();
    });
  }

   { projectId, validation };
}

Resources

• Lokalise Import Guide
• Supported File Formats
• Migration Case Studies

Flagship+ Skills

For advanced troubleshooting, see lokalise-common-errors.