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".
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 <jeremy@intentsolutions.io>
tags
["saas","lokalise","compliance"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
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.
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).
"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:
// Bulk update tags for release managementawait 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 contextawait lokalise.screenshots().create({
project_id: projectId,
screenshots: [
{
data: base64EncodedImage, // Base64 JPEG/PNG, max 6 MBtitle: "Welcome screen — mobile layout",
description: "Shows welcome.title and welcome.subtitle keys",
key_ids: [12345, 12346],
},
],
});
// Retrieve key with all metadataconst 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:
// Create a snapshot before a major updateconst snapshot = await lokalise.snapshots().create({
project_id: projectId,
title: `Pre-release v3.0 — ${newDate().toISOString()}`,
});
console.log(`Snapshot created: ${snapshot.snapshot_id}`);
// List snapshotsconst 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:
// Create a feature branchawait lokalise.branches().create({
project_id: projectId,
name: "feature/checkout-redesign",
});
// List branchesconst branches = await lokalise.branches().list({ project_id: projectId });
// Work on the branch — use the branch name in file operationsawait 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 readyawait 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:
// 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 untranslatedinclude_tags: ["release-3.0"],
filter_langs: ["en", "fr", "de", "ja"],
});
// Returns { bundle_url: "https://..." } — download the ZIP
For deploying translations into your CI/CD pipeline, see lokalise-deploy-integration. For handling API errors during data operations, see lokalise-common-errors.
