lokalise-prod-checklist

What this skill does

# Lokalise Production Checklist

## Overview

A structured pre-deployment checklist for Lokalise integrations covering nine verification areas: translation coverage, missing key detection, format validation, API token security, rate limit preparedness, fallback language configuration, download verification, OTA configuration, and contributor access review. Run through each section before any production deployment.

## Prerequisites

- Lokalise project with production API token
- `lokalise2` CLI installed and authenticated
- `curl` and `jq` available in your environment
- Access to the Lokalise dashboard (Team Owner or Admin role)
- Application codebase with i18n integration ready for deployment

## Instructions

### Step 1: Translation Coverage Audit

Verify that every supported locale meets the coverage threshold before deploying.

```bash
#!/bin/bash
# scripts/audit-translation-coverage.sh
set -euo pipefail

: "${LOKALISE_API_TOKEN:?Required}"
: "${LOKALISE_PROJECT_ID:?Required}"

REQUIRED_COVERAGE=100  # Percentage required for production
REQUIRED_LOCALES=("en" "de" "fr" "es" "ja")

echo "=== Translation Coverage Audit ==="

# Get project statistics from Lokalise API
STATS=$(curl -sf "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}/statistics" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}")

TOTAL_KEYS=$(echo "$STATS" | jq '.project_statistics.keys_total')
echo "Total keys in project: $TOTAL_KEYS"

# Get per-language statistics
LANGUAGES=$(curl -sf "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}/languages" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}")

FAILED=0
echo ""
echo "Locale   | Progress | Words     | Status"
echo "---------|----------|-----------|-------"

for locale in "${REQUIRED_LOCALES[@]}"; do
  progress=$(echo "$LANGUAGES" | jq -r ".languages[] | select(.lang_iso == \"${locale}\") | .statistics.progress")
  words=$(echo "$LANGUAGES" | jq -r ".languages[] | select(.lang_iso == \"${locale}\") | .statistics.words_to_do")

  if [[ -z "$progress" || "$progress" == "null" ]]; then
    echo "${locale}      | MISSING  | -         | FAIL"
    FAILED=1
    continue
  fi

  if (( $(echo "$progress < $REQUIRED_COVERAGE" | bc -l) )); then
    echo "${locale}      | ${progress}%   | ${words} remaining | FAIL"
    FAILED=1
  else
    echo "${locale}      | ${progress}%   | 0         | PASS"
  fi
done

echo ""
if [[ $FAILED -eq 1 ]]; then
  echo "RESULT: FAILED — Resolve incomplete translations before deploying."
  exit 1
fi
echo "RESULT: PASSED — All locales meet ${REQUIRED_COVERAGE}% coverage."
```

### Step 2: Missing Key Detection

Detect keys present in source code but absent from Lokalise, and vice versa.

```bash
#!/bin/bash
# scripts/detect-missing-keys.sh
set -euo pipefail

: "${LOKALISE_API_TOKEN:?Required}"
: "${LOKALISE_PROJECT_ID:?Required}"

echo "=== Missing Key Detection ==="

# Download current translation keys from Lokalise
TEMP_DIR=$(mktemp -d)
trap 'rm -rf "$TEMP_DIR"' EXIT

lokalise2 file download \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$LOKALISE_PROJECT_ID" \
  --format json \
  --original-filenames=true \
  --directory-prefix="" \
  --unzip-to "$TEMP_DIR/" 2>/dev/null

# Extract keys from Lokalise download
LOKALISE_KEYS=$(jq -r '[paths(scalars)] | map(join(".")) | .[]' "$TEMP_DIR/en.json" | sort)

# Extract keys referenced in source code (adjust pattern for your framework)
# React/i18next: t('key'), t("key"), <Trans i18nKey="key">
SOURCE_KEYS=$(grep -roh "t(['\"][^'\"]*['\"])" src/ 2>/dev/null \
  | sed "s/t(['\"]//;s/['\"])//" \
  | sort -u || true)

echo ""
echo "Keys in Lokalise:    $(echo "$LOKALISE_KEYS" | wc -l)"
echo "Keys in source code: $(echo "$SOURCE_KEYS" | wc -l)"

# Keys in code but not in Lokalise
MISSING_IN_LOKALISE=$(comm -23 <(echo "$SOURCE_KEYS") <(echo "$LOKALISE_KEYS") || true)
if [[ -n "$MISSING_IN_LOKALISE" ]]; then
  echo ""
  echo "MISSING IN LOKALISE (used in code but not uploaded):"
  echo "$MISSING_IN_LOKALISE" | head -20
  COUNT=$(echo "$MISSING_IN_LOKALISE" | wc -l)
  [[ $COUNT -gt 20 ]] && echo "  ... and $((COUNT - 20)) more"
fi

# Keys in Lokalise but not in code (potential dead keys)
ORPHANED=$(comm -13 <(echo "$SOURCE_KEYS") <(echo "$LOKALISE_KEYS") || true)
if [[ -n "$ORPHANED" ]]; then
  echo ""
  echo "ORPHANED IN LOKALISE (not referenced in code):"
  echo "$ORPHANED" | head -20
  COUNT=$(echo "$ORPHANED" | wc -l)
  [[ $COUNT -gt 20 ]] && echo "  ... and $((COUNT - 20)) more"
fi

if [[ -z "$MISSING_IN_LOKALISE" && -z "$ORPHANED" ]]; then
  echo ""
  echo "RESULT: PASSED — Keys are in sync."
fi
```

### Step 3: Format Validation

Validate that downloaded translation files are well-formed JSON and contain no placeholder mismatches.

```typescript
// scripts/validate-translation-format.ts
import fs from 'fs';
import path from 'path';

const LOCALES_DIR = 'src/locales';
const SOURCE_LOCALE = 'en';
const PLACEHOLDER_REGEX = /\{\{?\w+\}?\}|%[sd@]|\$\{[\w.]+\}/g;

interface ValidationResult {
  locale: string;
  valid: boolean;
  errors: string[];
}

function validate(): ValidationResult[] {
  const results: ValidationResult[] = [];
  const sourceFile = path.join(LOCALES_DIR, `${SOURCE_LOCALE}.json`);
  const sourceContent = JSON.parse(fs.readFileSync(sourceFile, 'utf-8'));
  const sourcePlaceholders = extractPlaceholders(sourceContent);

  for (const file of fs.readdirSync(LOCALES_DIR)) {
    if (!file.endsWith('.json')) continue;
    const locale = file.replace('.json', '');
    const errors: string[] = [];

    // Check 1: Valid JSON
    let content: Record<string, unknown>;
    try {
      content = JSON.parse(fs.readFileSync(path.join(LOCALES_DIR, file), 'utf-8'));
    } catch (e) {
      errors.push(`Invalid JSON: ${(e as Error).message}`);
      results.push({ locale, valid: false, errors });
      continue;
    }

    // Check 2: No empty string values (should be null or absent)
    const emptyKeys = findEmptyValues(content);
    if (emptyKeys.length > 0) {
      errors.push(`Empty string values: ${emptyKeys.slice(0, 5).join(', ')}${emptyKeys.length > 5 ? ` (+${emptyKeys.length - 5} more)` : ''}`);
    }

    // Check 3: Placeholder consistency
    const localePlaceholders = extractPlaceholders(content);
    for (const [key, expected] of Object.entries(sourcePlaceholders)) {
      const actual = localePlaceholders[key];
      if (actual && actual.sort().join(',') !== expected.sort().join(',')) {
        errors.push(`Placeholder mismatch in "${key}": expected [${expected}], got [${actual}]`);
      }
    }

    results.push({ locale, valid: errors.length === 0, errors });
  }

  return results;
}

function extractPlaceholders(obj: Record<string, unknown>, prefix = ''): Record<string, string[]> {
  const result: Record<string, string[]> = {};
  for (const [key, value] of Object.entries(obj)) {
    const fullKey = prefix ? `${prefix}.${key}` : key;
    if (typeof value === 'string') {
      const matches = value.match(PLACEHOLDER_REGEX);
      if (matches) result[fullKey] = matches;
    } else if (typeof value === 'object' && value !== null) {
      Object.assign(result, extractPlaceholders(value as Record<string, unknown>, fullKey));
    }
  }
  return result;
}

function findEmptyValues(obj: Record<string, unknown>, prefix = ''): string[] {
  const result: string[] = [];
  for (const [key, value] of Object.entries(obj)) {
    const fullKey = prefix ? `${prefix}.${key}` : key;
    if (value === '') result.push(fullKey);
    else if (typeof value === 'object' && value !== null) {
      result.push(...findEmptyValues(value as Record<string, unknown>, fullKey));
    }
  }
  return result;
}

// Run validation
const results = validate();
let failed = false;
for (const r of results) {
  const status = r.valid ? 'PASS' : 'FAIL';
  console.log(`[${status}] ${r.locale}`);
  r.errors.forEach(e => console.log(`       ${e}`));
  if (!r.valid) failed = true;
}
process.exit(failed ? 1 : 0);
```

### Step 4: API Token Security

```bash
echo "=== API Token Security A