Lokalise Core Workflow A

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}`);

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

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

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}`);
}

const updatedKey = await client.keys().update(KEY_ID, {
  project_id: PROJECT_ID,
  description: "Updated description",
  tags: ["onboarding", "v2.2", "reviewed"],
  is_hidden: false,
});

// 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'`);

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

// 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`);
}

// 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,
      });
    }
  }
}

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