lokalise-incident-runbook

name	lokalise-incident-runbook
description	Execute Lokalise incident response procedures with triage, mitigation, and postmortem. Use when responding to Lokalise-related outages, investigating errors, or running post-incident reviews for Lokalise integration failures. Trigger with phrases like "lokalise incident", "lokalise outage", "lokalise down", "lokalise on-call", "lokalise emergency", "translations broken".
allowed-tools	Read, Grep, Bash(curl:*), Bash(lokalise2:*)
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","lokalise","incident-response"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Lokalise Incident Runbook

Overview

Rapid-response procedures for Lokalise-related incidents in production. Covers quick diagnostics (API health, token validity, rate limit status), triage for five common failure modes (missing translations, stale translations, API outage, file upload failures, OTA failures), fallback to cached translations, and communication templates for stakeholder notification. Designed to be executed under pressure — each section is self-contained.

Prerequisites

• curl and jq available on the responder's machine
• Production Lokalise API token accessible (from secret manager or break-glass procedure)
• LOKALISE_PROJECT_ID known (check your deployment config or Lokalise dashboard)
• Access to application logs (Datadog, CloudWatch, GCP Logging, or equivalent)
• Incident communication channel (Slack, PagerDuty, or equivalent)

Instructions

Step 1: Quick Diagnostics (Run First)

Execute these three checks immediately to narrow the problem scope. Copy-paste into your terminal:

#!/bin/bash
# incident-diagnostics.sh — Run all three checks in sequence
set -uo pipefail

: "${LOKALISE_API_TOKEN:?Set LOKALISE_API_TOKEN before running diagnostics}"
: "${LOKALISE_PROJECT_ID:?Set LOKALISE_PROJECT_ID before running diagnostics}"

echo "=== 1. Lokalise API Health ==="
API_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" \
  "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}")

case "$API_STATUS" in
  200) echo "API: HEALTHY (200 OK)" ;;
  401) echo "API: AUTH FAILURE (401) — Token invalid or expired. Rotate immediately." ;;
  403) echo "API: FORBIDDEN (403) — Token lacks permissions for this project." ;;
  404)   ;;
  429)   ;;
  5*)    ;;
  000)   ;;
  *)     ;;


 
 
TOKEN_CHECK=$(curl -sf  \
  -H  2>/dev/null)

 [[ $? -eq 0 ]]; 
  PROJECT_NAME=$(  | jq -r )
  TEAM_ID=$(  | jq -r )
   
   
   

   
   


 
 
RATE_RESPONSE=$(curl -sI  \
  -H  2>/dev/null)

RATE_LIMIT=$(  | grep -i  |  -d  | awk )
RATE_REMAINING=$(  | grep -i  |  -d  | awk )

 [[ -n  ]]; 
   
   
   [[  -eq 0 ]];