Lokalise Data HandlingSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: lokalise-data-handling
description: 'Implement Lokalise translation data handling, PII management, and compliance
  patterns.

  Use when handling sensitive translation data, implementing data redaction,

  or ensuring compliance with privacy regulations for Lokalise integrations.

  Trigger with phrases like "lokalise data", "lokalise PII",

  "lokalise GDPR", "lokalise data retention", "lokalise privacy", "lokalise compliance".

  '
allowed-tools: Read, Write, Edit
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- compliance
compatibility: Designed for Claude Code
---
# Lokalise Data Handling

## Overview

Lokalise manages translation data through keys, translations, snapshots, and branches. This skill covers the translation data lifecycle (create, update, export), key metadata management (tags, descriptions, screenshots), translation snapshots for versioning, branch-based translation isolation, export format handling (JSON flat/nested, XLIFF, PO), character encoding (UTF-8 BOM handling), and plural form support across locales.

## Prerequisites

- `@lokalise/node-api` SDK installed (`npm install @lokalise/node-api`)
- API token with read/write access to the target project
- Understanding of i18n key naming conventions for your project
- `lokalise2` CLI for bulk file operations (optional)

## Instructions

### 1. Understand the Translation Data Lifecycle

Translation data in Lokalise follows this flow: **Create keys** (with platforms, tags, descriptions) -> **Add base translations** (source language) -> **Translate** (manually or via integrations) -> **Review** (proofread flag) -> **Export** (download to codebase).

Create keys with metadata that helps translators:

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

### 2. Manage Key Metadata

Tags, descriptions, and screenshots help translators understand context. Keep metadata current:

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

### 3. Use Snapshots for Translation Versioning

Snapshots capture the entire project state at a point in time. Create them before bulk changes:

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

Snapshots are immutable. Restoring creates a new project — it does not overwrite the current one.

### 4. Use Branches for Translation Isolation

Branches let you work on translations for a feature without affecting production strings:

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

### 5. Handle Export Formats

Lokalise supports multiple export formats. Choose based on your stack:

```typescript
// 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
```

```typescript
// Download as nested JSON (common for namespaced i18n)
const nestedJson = await lokalise.files().download({
  project_id: projectId,
  format: "json",

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.