lokalise-reference-architecture

What this skill does

# Lokalise Reference Architecture

## Overview

A production-ready architecture for integrating Lokalise into web applications. Covers the end-to-end translation flow from source code through CI/CD and Lokalise to deployed translations, recommended project structure for i18n, file organization conventions, multi-app translation sharing, and the tradeoffs between OTA (over-the-air) and build-time translation loading.

## Prerequisites

- Node.js 18+ with TypeScript
- `@lokalise/node-api` SDK installed (`npm install @lokalise/node-api`)
- An i18n framework selected (i18next, react-intl, vue-i18n, or equivalent)
- Lokalise project created with at least one source language configured
- Basic understanding of CI/CD pipelines (GitHub Actions, GitLab CI, or equivalent)

## Instructions

### Step 1: Architecture Diagram

The translation lifecycle follows this flow:

```
┌─────────────┐     ┌──────────┐     ┌─────────────┐
│ Source Code  │────▶│  CI/CD   │────▶│  Lokalise   │
│             │     │ (upload) │     │  (TMS)      │
│ en.json     │     └──────────┘     │             │
│ t('key')    │                      │  ┌────────┐ │
└─────────────┘                      │  │Transla-│ │
                                     │  │ tors   │ │
                                     │  └────────┘ │
┌─────────────┐     ┌──────────┐     │             │
│   Deploy    │◀────│  CI/CD   │◀────│  Download   │
│             │     │ (build)  │     │             │
│  CDN/Server │     └──────────┘     └─────────────┘
└──────┬──────┘                      ┌─────────────┐
       │                             │  Lokalise   │
       │         (OTA path)          │  OTA CDN    │
       │◀────────────────────────────│             │
       │                             └─────────────┘
┌──────▼──────┐
│    Users    │
│  (browser/  │
│   mobile)   │
└─────────────┘
```

**Two delivery paths:**

1. **Build-time** (solid arrows): Translations downloaded during CI build, bundled into the application. Changes require a new deployment.
2. **OTA** (dashed arrow): Translations fetched from Lokalise CDN at runtime. Changes appear without redeployment. Adds a network dependency.

### Step 2: Project Structure for i18n

Organize your codebase to separate translation concerns from business logic:

```
project-root/
├── src/
│   ├── i18n/
│   │   ├── index.ts              # i18n initialization and configuration
│   │   ├── client.ts             # Lokalise API client wrapper
│   │   ├── loader.ts             # Translation loader (build-time or OTA)
│   │   ├── fallback.ts           # Fallback translation logic
│   │   ├── types.ts              # TypeScript types for translation keys
│   │   └── middleware.ts         # Express/Next.js locale detection middleware
│   │
│   ├── locales/
│   │   ├── en.json               # Source language (committed to git)
│   │   ├── de.json               # Downloaded from Lokalise (gitignored or committed)
│   │   ├── fr.json
│   │   ├── es.json
│   │   └── ja.json
│   │
│   ├── locales-fallback/         # Static fallback copy (always committed)
│   │   ├── en.json
│   │   ├── de.json
│   │   └── ...
│   │
│   └── components/
│       └── ...                   # Components use t('key') from i18n
│
├── scripts/
│   ├── lokalise-pull.sh          # Download translations from Lokalise
│   ├── lokalise-push.sh          # Upload source strings to Lokalise
│   ├── validate-translations.ts  # Check coverage, placeholders, format
│   └── generate-types.ts         # Generate TypeScript types from en.json
│
├── .github/workflows/
│   ├── lokalise-upload.yml       # Upload on push to main
│   └── lokalise-download.yml     # Download during build
│
└── lokalise.config.ts            # Lokalise project configuration
```

### Step 3: Core Configuration

```typescript
// src/i18n/index.ts
import i18next from 'i18next';
import { initReactI18next } from 'react-i18next';  // or vue-i18n, svelte-i18n, etc.
import en from '../locales/en.json';

export const SUPPORTED_LOCALES = ['en', 'de', 'fr', 'es', 'ja'] as const;
export type SupportedLocale = typeof SUPPORTED_LOCALES[number];
export const DEFAULT_LOCALE: SupportedLocale = 'en';

i18next
  .use(initReactI18next)
  .init({
    resources: { en: { translation: en } },
    lng: DEFAULT_LOCALE,
    fallbackLng: DEFAULT_LOCALE,
    supportedLngs: [...SUPPORTED_LOCALES],
    load: 'languageOnly',             // 'de' not 'de-DE'
    returnEmptyString: false,         // Treat '' as missing → use fallback
    interpolation: { escapeValue: false },
    detection: {
      order: ['cookie', 'navigator', 'htmlTag'],
      caches: ['cookie'],
    },
  });

export default i18next;
```

### Step 4: Lokalise API Client Wrapper

```typescript
// src/i18n/client.ts
import { LokaliseApi } from '@lokalise/node-api';

interface LokaliseClientConfig {
  apiToken: string;
  projectId: string;
  rateLimitPerSec?: number;
}

export class LokaliseClient {
  private api: LokaliseApi;
  private projectId: string;
  private requestTimestamps: number[] = [];
  private maxRequestsPerSec: number;

  constructor(config: LokaliseClientConfig) {
    this.api = new LokaliseApi({ apiKey: config.apiToken });
    this.projectId = config.projectId;
    this.maxRequestsPerSec = config.rateLimitPerSec ?? 6;
  }

  /**
   * Download all translation files as a zip bundle URL.
   */
  async downloadTranslations(options?: {
    format?: string;
    branch?: string;
  }): Promise<string> {
    await this.rateLimit();
    const projectId = options?.branch
      ? `${this.projectId}:${options.branch}`
      : this.projectId;

    const response = await this.api.files().download(projectId, {
      format: options?.format ?? 'json',
      original_filenames: true,
      directory_prefix: '',
      export_empty_as: 'base',
      export_sort: 'first_added',
    });

    return response.bundle_url;
  }

  // Additional methods: listKeys(), getStatistics(), uploadFile()
  // follow the same pattern — call this.rateLimit() before each API call.

  /**
   * Simple rate limiter: 6 requests per second max.
   */
  private async rateLimit(): Promise<void> {
    const now = Date.now();
    this.requestTimestamps = this.requestTimestamps.filter(t => now - t < 1000);

    if (this.requestTimestamps.length >= this.maxRequestsPerSec) {
      const oldestInWindow = this.requestTimestamps[0];
      const waitMs = 1000 - (now - oldestInWindow);
      if (waitMs > 0) {
        await new Promise(resolve => setTimeout(resolve, waitMs));
      }
    }

    this.requestTimestamps.push(Date.now());
  }
}
```

### Step 5: File Organization Conventions

Follow these conventions for translation file organization:

**Flat keys** (recommended for most projects — simpler grep, no nesting ambiguity):

```json
{
  "homepage.hero.title": "Welcome to MyApp",
  "homepage.hero.subtitle": "The best app ever",
  "settings.profile.name_label": "Full Name",
  "errors.not_found": "Page not found"
}
```

**Nested keys** work better for large projects with clear module boundaries, where each top-level key maps to a feature area. Both formats are supported by Lokalise and i18next.

**Key naming conventions:**

- Use dot notation: `module.section.element`
- Use snake_case for key segments: `user_profile`, not `userProfile`
- Prefix by feature area: `checkout.payment.card_label`
- Use consistent suffixes: `_title`, `_label`, `_button`, `_error`, `_placeholder`
- Keep keys under 100 characters (Lokalise hard limit is 1024 chars per key name)

**File naming:**

- One file per locale: `en.json`, `de.json`, `fr.json`
- For large apps, split by namespace: `common.json`, `auth.json`, `dashboard.json`
- Namespace files go in subdirectories: `locales/en/common.json`, `locales/en/auth.json`

### Step 6: Multi-App Translation Sharing

When multiple applications share translations (e.g., web app + mobile app + marketing site):

```
Lokalise Project: "MyCompany Shared"
├── Tags: shared, web-only, mobile-only, marketing-only
│
├── Shared keys (tag