Developer API

Locale Owl provides a REST API that follows i18next conventions. Authenticate with Bearer tokens, fetch translations by project/locale/namespace, and integrate with your CI/CD pipeline.

Authentication

Locale Owl uses two types of authentication:

• Bearer tokens — for dashboard API calls (login, project management, publishing). Generated at login.
• Project API keys — for SDK endpoints like missing key reporting. Find your key in Admin UI → Project Settings → API Key.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://cdn.localeowl.com/api/namespaces/PROJECT_ID/en/landing

REST Endpoints

Get Translations

Fetch published translations for a specific locale and namespace:

Response Format

All translation endpoints return nested JSON matching the i18next format:

{
  "hero": {
    "title": "Ship your product in every language",
    "subtitle": "The developer-first localization platform...",
    "cta": {
      "primary": "Start for Free",
      "secondary": "View Documentation"
    }
  }
}

Import Translations

Upload a JSON file to merge into your draft translations:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "locale=en" \
  -F "namespace=landing" \
  https://cdn.localeowl.com/api/projects/PROJECT_ID/import

The import supports both nested and flat JSON formats. Existing keys are merged (not overwritten) by default.

SDK Integration

i18next

Point your i18next backend to the Locale Owl CDN:

import i18next from 'i18next';
import HttpBackend from 'i18next-http-backend';

i18next.use(HttpBackend).init({
  backend: {
    loadPath: 'https://cdn.localeowl.com/api/namespaces/PROJECT_ID/{{lng}}/{{ns}}',
    // Enable saveMissing to auto-report untranslated keys
    addPath: 'https://cdn.localeowl.com/api/missing/PROJECT_ID/{{lng}}/{{ns}}',
    customHeaders: {
      'x-api-key': 'YOUR_PROJECT_API_KEY'  // From Project Settings → API Key
    }
  },
  saveMissing: true,  // Enable in development only
  lng: 'en',
  ns: ['landing', 'dashboard'],
  defaultNS: 'landing'
});

React / Next.js

Use the standard react-i18next provider with the same backend config. Translations load on demand from the CDN edge.

CI/CD Integration

Pull Script

Use the included pull script to fetch translations at build time:

# In your CI/CD pipeline
TRANSLATIONS_PROJECT_ID=your-project-id \
TRANSLATIONS_API=https://cdn.localeowl.com \
bun run scripts/pull-translations.ts

GitHub Actions Example

# .github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1

      - name: Pull translations
        env:
          TRANSLATIONS_PROJECT_ID: ${{ secrets.LOCALE_OWL_PROJECT_ID }}
          TRANSLATIONS_API: https://cdn.localeowl.com
        run: bun run scripts/pull-translations.ts

      - name: Build
        run: bun run build