lokalise-multi-env-setup

name	lokalise-multi-env-setup
description	Configure Lokalise across development, staging, and production environments. Use when setting up multi-environment deployments, configuring per-environment secrets, or implementing environment-specific Lokalise configurations. Trigger with phrases like "lokalise environments", "lokalise staging", "lokalise dev prod", "lokalise environment setup", "lokalise config by env".
allowed-tools	Read, Write, Edit, Bash(aws:*), Bash(gcloud:*), Bash(vault:*)
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","lokalise","deployment"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Lokalise Multi-Environment Setup

Overview

Configure Lokalise for isolated development, staging, and production environments. Two strategies are covered: separate Lokalise projects per environment (strongest isolation) and Lokalise branching within a single project (simpler management). Both approaches include secret management, environment-aware configuration, and a promotion workflow that moves translations through the pipeline from dev to production without cross-contamination.

Prerequisites

• Lokalise Team or Enterprise plan (branching requires Team plan or higher)
• One Lokalise API token per environment, each scoped to minimum required permissions
• Secret management system: GitHub Secrets, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault
• Node.js 18+ with @lokalise/node-api SDK installed
• Environment variable NODE_ENV (or equivalent) set in each deployment target

Instructions

Step 1: Choose Your Strategy

Option A — Separate projects per environment (recommended for teams > 5 translators or strict compliance):

Environment	Lokalise Project	Purpose
Development	MyApp (Dev)	Rapid iteration, machine translations OK
Staging	MyApp (Staging)	QA review, translator proofing
Production	MyApp (Prod)	Approved translations only

Option B — Single project with Lokalise branching (simpler for small teams):

Branch	Purpose
main	Production translations
staging	QA translations under review
dev	Work-in-progress translations

Step 2: Environment-Aware Configuration

Create a configuration module that selects the correct Lokalise project and credentials based on the runtime environment:

// src/config/lokalise.ts
interface LokaliseEnvConfig {
  : ;
  : ;
  : ;
  ?: ;           
  : ;
  : ;
  : ;
  : ;
}

 : <, <,  | >> = {
  : {
    : ,
    : ,            
    : ,
    : ,
    : ,
  },
  : {
    : ,
    :  * ,  
    : ,
    : ,
    : ,
  },
  : {
    : ,
    :  * , 
    : ,
    : ,
    : ,       
  },
};

  ():  {
   env = process.. || ;
   base = [env];

   (!base) {
      ();
  }

   apiToken = process..;
   projectId = process..;

   (!apiToken) {
      ();
  }
   (!projectId) {
      ();
  }

   {
    ...base,
    apiToken,
    projectId,
    : process..,  
  };
}