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 authenticatedcurl 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.
#!/bin/bash
set -euo pipefail
: "${LOKALISE_API_TOKEN:?Required}"
: "${LOKALISE_PROJECT_ID:?Required}"
REQUIRED_COVERAGE=100
REQUIRED_LOCALES=("en" "de" "fr" "es" "ja")
echo "=== Translation Coverage Audit ==="
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"
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.
#!/bin/bash
set -euo pipefail
: "${LOKALISE_API_TOKEN:?Required}"
: "${LOKALISE_PROJECT_ID:?Required}"
echo "=== Missing Key Detection ==="
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
LOKALISE_KEYS=$(jq -r '[paths(scalars)] | map(join(".")) | .[]' "$TEMP_DIR/en.json" | sort)
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)"
MISSING_IN_LOKALISE=$( -23 <( ) <( ) || )
[[ -n ]];
| -20
COUNT=$( | -l)
[[ -gt 20 ]] &&
ORPHANED=$( -13 <( ) <( ) || )
[[ -n ]];
| -20
COUNT=$( | -l)
[[ -gt 20 ]] &&
[[ -z && -z ]];
Step 3: Format Validation
Validate that downloaded translation files are well-formed JSON and contain no placeholder mismatches.
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()) ;
locale = file.(, );
: [] = [];
: <, >;
{
content = .(fs.(path.(, file), ));
} (e) {
errors.();
results.({ locale, : , errors });
;
}
emptyKeys = (content);
(emptyKeys. > ) {
errors.();
}
localePlaceholders = (content);
( [key, expected] .(sourcePlaceholders)) {
actual = localePlaceholders[key];
(actual && actual.().() !== expected.().()) {
errors.();
}
}
results.({ locale, : errors. === , errors });
}
results;
}
(): <, []> {
: <, []> = {};
( [key, value] .(obj)) {
fullKey = prefix ? : key;
( value === ) {
matches = value.();
(matches) result[fullKey] = matches;
} ( value === && value !== ) {
.(result, (value <, >, fullKey));
}
}
result;
}
(): [] {
: [] = [];
( [key, value] .(obj)) {
fullKey = prefix ? : key;
(value === ) result.(fullKey);
( value === && value !== ) {
result.(...(value <, >, fullKey));
}
}
result;
}
results = ();
failed = ;
( r results) {
status = r. ? : ;
.();
r..( .());
(!r.) failed = ;
}
process.(failed ? : );
Step 4: API Token Security
echo "=== API Token Security Audit ==="
HARDCODED=$(grep -r "X-Api-Token" --include="*.ts" --include="*.js" --include="*.json" \
-l src/ 2>/dev/null | grep -v node_modules || true)
if [[ -n "$HARDCODED" ]]; then
echo "FAIL: API token may be hardcoded in: $HARDCODED"
exit 1
fi
GIT_SECRETS=$(git log --all -p --diff-filter=A -- '*.env' '*.env.*' 2>/dev/null \
| grep -i "LOKALISE_API_TOKEN=" | head -5 || true)
if [[ -n "$GIT_SECRETS" ]]; then
echo "FAIL: Token found in git history. Rotate immediately."
exit 1
fi
if ! grep -q "\.env" .gitignore 2>/dev/null; then
echo "WARN: .env not in .gitignore"
fi
TOKEN_RESPONSE=$(curl -sf "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}" \
-H "X-Api-Token: ${LOKALISE_API_TOKEN}" -o /dev/null -w "%{http_code}")
if [[ "" == ]];
1
Step 5: Rate Limit Preparedness
echo "=== Rate Limit Readiness ==="
RATE_LIMIT_HANDLING=$(grep -r "429\|rate.limit\|retry-after\|rateLimitRetry" \
--include="*.ts" --include="*.js" src/ 2>/dev/null | head -5 || true)
if [[ -z "$RATE_LIMIT_HANDLING" ]]; then
echo "WARN: No rate limit handling detected in source code."
echo " Add retry logic with exponential backoff for 429 responses."
echo " Lokalise limit: 6 requests/second per API token."
else
echo "PASS: Rate limit handling detected"
echo "$RATE_LIMIT_HANDLING"
fi
Step 6: Fallback Language Configuration
Verify the application gracefully falls back when a translation is missing.
import i18next from 'i18next';
i18next.init({
fallbackLng: 'en',
load: 'languageOnly',
returnEmptyString: false,
missingKeyHandler: (lngs, ns, key) => {
console.warn(`Missing translation: ${key} for ${lngs.join(', ')}`);
},
interpolation: {
escapeValue: false,
},
});
Step 7: Download Verification
Test that the full download-build cycle works end-to-end.
echo "=== Download Verification ==="
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="" \
--export-empty-as=base \
--unzip-to "$TEMP_DIR/" 2>&1
FILE_COUNT=$(find "$TEMP_DIR" -name "*.json" | wc -l)
echo "Downloaded $FILE_COUNT locale files"
if [[ $FILE_COUNT -eq 0 ]]; then
echo "FAIL: No files downloaded"
exit 1
fi
for f in "$TEMP_DIR"/*.json; do
if ! jq empty "$f" 2>/dev/null; then
echo "FAIL: Invalid JSON: $f"
exit 1
fi
keys=$(jq '[paths(scalars)] | length' "$f")
locale=$(basename "$f" .json)
Step 8: OTA Configuration (If Applicable)
If using Lokalise OTA (over-the-air) translations for mobile or web:
echo "=== OTA Configuration Check ==="
if [[ -z "${LOKALISE_OTA_TOKEN:-}" ]]; then
echo "INFO: OTA not configured (LOKALISE_OTA_TOKEN not set). Skip if not using OTA."
else
OTA_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" \
"https://ota.lokalise.com/v3/public/${LOKALISE_OTA_TOKEN}/")
if [[ "$OTA_STATUS" == "200" ]]; then
echo "PASS: OTA endpoint reachable"
else
echo "FAIL: OTA endpoint returned HTTP $OTA_STATUS"
fi
echo "INFO: Check Lokalise dashboard > OTA > Settings for freeze windows before deploy"
fi
Step 9: Contributor Access Review
echo "=== Contributor Access Review ==="
CONTRIBUTORS=$(curl -sf "https://api.lokalise.com/api2/teams" \
-H "X-Api-Token: ${LOKALISE_API_TOKEN}")
echo "Review the following in the Lokalise dashboard before go-live:"
echo " 1. Remove any test/demo contributors from the production project"
echo " 2. Verify all contributors have the minimum required role"
echo " 3. Ensure no shared/generic accounts exist"
echo " 4. Confirm two-factor authentication is enabled for admins"
echo " 5. Review and remove any unused API tokens"
echo ""
echo "Roles reference:"
echo " - Admin: Full access (limit to 2-3 people)"
echo " - Manager: Can manage contributors and keys"
echo " - Developer: Upload/download, no contributor management"
echo " - Translator: Translate only, no key management"
echo ""
echo "ACTION: Manually verify in Lokalise dashboard > Team > Members"
Output
A complete pre-deployment report covering:
- Translation coverage percentage per locale (must be 100% for production)
- Missing and orphaned key counts
- Format validation results (JSON validity, placeholder consistency)
- Security audit results (no hardcoded tokens, proper gitignore)
- Rate limit handling confirmation
- Fallback language configuration status
- Download verification (end-to-end test)
- OTA readiness (if applicable)
- Contributor access review action items
Error Handling
| Alert | Condition | Severity | Action |
|---|
| Incomplete translations | Any locale < 100% | P1 — Blocks deploy | Complete translations or add missing keys |
| Hardcoded API token | Token found in source | P1 — Blocks deploy | Remove from code, rotate token immediately |
| Token in git history | Token committed previously | P1 — Blocks deploy | Rotate token, consider git filter-repo |
| Download produces 0 files | API error or empty project | P1 — Blocks deploy | Check project ID, token permissions, Lokalise status |
| Placeholder mismatch | {{name}} missing in translation | P2 — Warning | Fix in Lokalise, re-download |
| No rate limit handling | Missing 429 retry logic | P2 — Warning | Add retry with backoff before high-traffic launch |
| Empty string values | Untranslated keys exported as "" | P3 — Info | Use --export-empty-as=base or skip |
Examples
Quick Spot-Check (Single Locale)
curl -sf "https://api.lokalise.com/api2/projects/${LOKALISE_PROJECT_ID}/languages" \
-H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
| jq '.languages[] | select(.lang_iso == "de") | {locale: .lang_iso, progress: .statistics.progress, words_remaining: .statistics.words_to_do}'
Resources
Next Steps
- After passing all checks, deploy using your standard pipeline
- Set up
lokalise-incident-runbook for post-launch incident response
- Configure monitoring alerts for translation-related errors (missing keys, API failures)
- Schedule quarterly re-runs of this checklist for ongoing compliance
