Lokalise Data Handling

import { LokaliseApi } from "@lokalise/node-api";
const lokalise = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

// Create keys with rich metadata
await lokalise.keys().create({
  project_id: projectId,
  keys: [
    {
      key_name: {
        ios: "welcome.title",
        android: "welcome_title",
        web: "welcome.title",
        other: "welcome.title",
      },
      description: "Main heading on the welcome screen shown after signup",
      platforms: ["web", "ios", "android"],
      tags: ["onboarding", "v2.1"],
      base_translations: [
        { language_iso: "en", translation: "Welcome to {{appName}}" },
      ],
      is_plural: false,
      is_hidden: false,
    },
  ],
});

// Bulk update tags for release management
await lokalise.keys().bulk_update({
  project_id: projectId,
  keys: [
    { key_id: 12345, tags: ["release-3.0", "reviewed"] },
    { key_id: 12346, tags: ["release-3.0", "needs-review"] },
  ],
});

// Add a screenshot for visual context
await lokalise.screenshots().create({
  project_id: projectId,
  screenshots: [
    {
      data: base64EncodedImage, // Base64 JPEG/PNG, max 6 MB
      title: "Welcome screen — mobile layout",
      description: "Shows welcome.title and welcome.subtitle keys",
      key_ids: [12345, 12346],
    },
  ],
});

// Retrieve key with all metadata
const key = await lokalise.keys().get(keyId, {
  project_id: projectId,
  disable_references: 0, // include reference language info
});
console.log(key.key_name, key.tags, key.description);

// Create a snapshot before a major update
const snapshot = await lokalise.snapshots().create({
  project_id: projectId,
  title: `Pre-release v3.0 — ${new Date().toISOString()}`,
});
console.log(`Snapshot created: ${snapshot.snapshot_id}`);

// List snapshots
const snapshots = await lokalise.snapshots().list({
  project_id: projectId,
  limit: 20,
});
snapshots.items.forEach((s) =>
  console.log(`${s.snapshot_id}: ${s.title} (${s.created_at})`)
);

// Restore a snapshot (creates a NEW project with the snapshot data)
const restored = await lokalise.snapshots().restore(snapshotId, {
  project_id: projectId,
});
console.log(`Restored to new project: ${restored.project_id}`);

// Create a feature branch
await lokalise.branches().create({
  project_id: projectId,
  name: "feature/checkout-redesign",
});

// List branches
const branches = await lokalise.branches().list({ project_id: projectId });

// Work on the branch — use the branch name in file operations
await lokalise.files().upload({
  project_id: projectId,
  data: base64FileContent,
  filename: "en.json",
  lang_iso: "en",
  use_automations: true,
  branch: "feature/checkout-redesign", // target the branch
});

// Merge branch back to main when translations are ready
await lokalise.branches().merge(branchId, {
  project_id: projectId,
  force_current: false, // false = conflict detection enabled
});

// Download as flat JSON (React, Next.js, Vue)
const flatJson = await lokalise.files().download({
  project_id: projectId,
  format: "json",
  original_filenames: false,
  bundle_structure: "locales/%LANG_ISO%.json",
  json_unescaped_slashes: true,
  export_empty_as: "base",    // use base language for untranslated
  include_tags: ["release-3.0"],
  filter_langs: ["en", "fr", "de", "ja"],
});
// Returns { bundle_url: "https://..." } — download the ZIP

// Download as nested JSON (common for namespaced i18n)
const nestedJson = await lokalise.files().download({
  project_id: projectId,
  format: "json",
  original_filenames: false,
  bundle_structure: "locales/%LANG_ISO%/%FILENAME%.json",
  json_unescaped_slashes: true,
  export_key_as: "key_name_dots_to_nested", // a.b.c → {a:{b:{c:"..."}}}
});

# Export as XLIFF 2.0 (for professional translation agencies)
lokalise2 file download \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  --format xliff \
  --dest ./translations/ \
  --include-tags "release-3.0"

# Export as PO/POT (for gettext-based projects)
lokalise2 file download \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  --format po \
  --dest ./locales/ \
  --export-empty-as base

// Remove UTF-8 BOM if present (some editors add it)
function stripBOM(content: string): string {
  return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
}

// Validate JSON translation files after download
import { readFileSync } from "fs";

function loadTranslations(filePath: string): Record<string, string> {
  const raw = readFileSync(filePath, "utf-8");
  const clean = stripBOM(raw);
  try {
    return JSON.parse(clean);
  } catch (e) {
    throw new Error(
      `Invalid JSON in ${filePath}: ${(e as Error).message}. ` +
      `Check for encoding issues or unescaped characters.`
    );
  }
}

# Upload with explicit encoding
lokalise2 file upload \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  --file ./locales/en.json \
  --lang-iso en \
  --convert-placeholders true

// Create a plural key
await lokalise.keys().create({
  project_id: projectId,
  keys: [
    {
      key_name: "items.count",
      is_plural: true,
      platforms: ["web"],
      base_translations: [
        {
          language_iso: "en",
          translation: JSON.stringify({
            one: "{{count}} item",
            other: "{{count}} items",
          }),
        },
      ],
    },
  ],
});

{
  "items.count": {
    "one": "{{count}} item",
    "other": "{{count}} items"
  }
}