API-First Localization: Building Translation Into Your Development Workflow

API-First Localization: Building Translation Into Your Development Workflow

Key Takeaways

• API-first localization replaces manual file exchange with automated sync between your codebase and translation management system
• CLI tools and CI/CD integrations enable push/pull workflows that keep translations in sync with every deployment
• Webhook-based notifications trigger builds when translations are updated, enabling continuous localization
• API-first approaches reduce time-to-market for new languages from weeks to hours

What Is API-First Localization?

API-first localization is an approach where the translation management system (TMS) provides programmatic access to all translation workflows through REST APIs, CLI tools, and webhooks. Instead of manually exporting/importing translation files, developers integrate translation sync directly into their build and deployment pipelines.

The Traditional vs. API-First Workflow

Traditional (File-Based)

1. Developer exports source strings to a file (JSON, XLIFF, etc.)
2. File is uploaded to TMS or sent to translators via email
3. Translated files are returned after days/weeks
4. Developer downloads and places files in the correct directories
5. Developer commits and deploys

Problems: Manual steps, version drift, merge conflicts, slow cycle times.

API-First

1. Developer pushes new strings via CLI: better-i18n push
2. TMS notifies translators of new content
3. Translators work in the TMS editor with full context
4. Webhook triggers CI/CD when translations are complete
5. Build pulls latest translations: better-i18n pull
6. Deployment includes updated translations automatically

Benefits: No manual file handling, continuous sync, faster cycle times.

Core Components of API-First Localization

REST API

The TMS API provides endpoints for:

POST /api/keys          — Create new translation keys
GET  /api/translations  — Fetch translations for a locale
PUT  /api/translations  — Update translations
GET  /api/projects      — List projects and their status
POST /api/upload        — Upload source files
GET  /api/download      — Download translated files

CLI Tool

A command-line tool that wraps the API for developer convenience:

# Push new source strings to TMS
better-i18n push

# Pull latest translations
better-i18n pull --locale=de,fr,ja

# Check translation status
better-i18n status

# Scan codebase for untranslated strings
better-i18n scan

Webhooks

Event-driven notifications when translations change:

{
  "event": "translations.completed",
  "project": "my-app",
  "locale": "de",
  "completed_keys": 142,
  "total_keys": 142
}

Use webhooks to trigger CI/CD pipelines, Slack notifications, or automated deployments.

CI/CD Integration

Integrate translation sync into your build pipeline:

# GitHub Actions example
- name: Pull translations
  run: better-i18n pull --all
  env:
    BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}

- name: Build
  run: npm run build

Benefits of API-First Localization

Implementation Patterns

Pattern 1: Build-Time Pull

Pull translations during the build step. Translations are bundled into the app at build time.

Best for: Static sites, pre-rendered pages, mobile apps.

Pattern 2: Runtime Fetch

Fetch translations from the API at runtime. Enables instant updates without redeployment.

Best for: SPAs, dynamic web apps, real-time content.

Pattern 3: Hybrid

Pull translations at build time for initial load, fetch updates at runtime for hot-fixes.

Best for: Production apps that need both performance and flexibility.

FAQ

Do I need to change my file format to use API-first localization? No. Most API-first TMS platforms support standard formats (JSON, XLIFF, YAML, .strings, .xml) and handle format conversion automatically.

How do I handle translation keys that are renamed or deleted? The CLI scan command detects unused keys. API endpoints allow batch key operations. Most TMS platforms track key lifecycle and flag orphaned translations.

What happens if the API is down during a build? Use cached translations as fallback. Store the last successful pull in version control so builds always have a baseline even if the API is unreachable.

How do I manage translations for multiple environments? Use project-level or branch-level namespacing. Some TMS platforms support environment-specific overrides (staging, production) for the same project.

Is API-first localization suitable for small projects? Yes. The CLI push/pull workflow is simpler than manual file management even for projects with a few hundred strings. The overhead of setting up API integration is minimal compared to the time saved.