Build with LexiSync

Get started

LexiSync is a hosted SaaS. You don’t install a server — create an account, grab keys, and point your app at the cloud API / CDN.

npm install lexisync
# optional peers for React apps:
npm install lexisync-react i18next react-i18next

export LEXISYNC_API_KEY=sk_your_secret
export LEXISYNC_API_URL=https://lexisync.app

npx lexisync sync -p YOUR_PROJECT_ID -f ./locales/en.json -l en
npx lexisync publish -p YOUR_PROJECT_ID -v production

Dashboard UI (user guide)

Everything product managers and developers need lives under /dashboard.

Projects

• List of projects in your org; click one to open the catalog editor.
• Create a project from the dashboard (subject to plan limits).
• Usage meters: keys, storage, project count vs plan caps.

Translate & publish (catalog editor)

• Columns to show — toggle languages (e.g. en + nl) side by side. Blur a cell to save the working copy.
• Add language — register a new locale code; fill translations then publish.
• AI translate (Pro) — fills only missing/empty targets (or keys where source changed after a prior AI run). 60s cooldown bar between runs.
• Publish catalog — freezes the entire catalog (all namespaces × all languages) into a named version such as production. Not just the visible columns.
• CDN stats & audit — download hits per version; who published when.

API keys (Settings)

• sk_… — secret, write + read. CLI, CI, server only.
• pub_… — public, read-only (safe-ish for browser if you accept catalog exposure).

Billing

Upgrade to Pro via Stripe Checkout, manage cards/invoices in the Stripe Customer Portal. Failed payments get a grace window; then entitlements fall back to Free limits.

Language switcher (platform UI)

The LexiSync product UI itself is localized. The switcher loads available languages from the published catalog CDN for the dogfood project — same mechanism your apps use.

Concepts

Locize-style publish workflow

# 1) Source
npx lexisync sync -p $PROJECT_ID -f ./locales/en/common.json -l en -n common

# 2) Optional: more namespaces / languages
npx lexisync sync -p $PROJECT_ID -f ./locales/nl/common.json -l nl -n common

# 3) After UI review…
npx lexisync publish -p $PROJECT_ID -v production

# 4) App loads:
# GET https://lexisync.app/api/cdn/$PROJECT_ID/production/en/common

npm package: lexisync

Official package: CLI, i18next backend, and small HTTP client. Node.js ≥ 18.

npm install lexisync
# i18next peer when using the backend:
npm install i18next

npx lexisync --help

Config file: ~/.lexisync/config.json. Env overrides:

CLI reference

lexisync init [-n name]     # bootstrap hints / org notes
lexisync sync  -p <projectId> -f <file.json> -l <lng> [-n namespace]
lexisync pull  -p <projectId> -n <ns> -l <lng> [-v latest|production] -o <file>
lexisync publish -p <projectId> -v <version>
lexisync versions -p <projectId>

# Global where supported:
#   --api-url  --api-key
#   env LEXISYNC_API_URL  LEXISYNC_API_KEY

sync

Uploads a nested or flat JSON locale file into the project working copy. Creates namespaces and keys as needed. Subject to plan limits (keys, source words, storage).

publish

Snapshots the full working copy to a named version. Overwriting the same version name replaces the CDN catalog for that tag.

pull

Downloads one namespace × language for offline builds or git commits.

i18next backend

Drop-in backend that reads from the LexiSync CDN (and can write missing keys to latest).

import i18next from 'i18next';
import LexiSyncBackend from 'lexisync';

await i18next.use(LexiSyncBackend).init({
  lng: 'en',
  fallbackLng: 'en',
  ns: ['common', 'auth'],
  defaultNS: 'common',
  backend: {
    projectId: process.env.LEXISYNC_PROJECT_ID,
    apiUrl: 'https://lexisync.app',
    // Use public or secret key for saveMissing; CDN reads need no key
    apiKey: process.env.LEXISYNC_API_KEY,
    version: process.env.NODE_ENV === 'production' ? 'production' : 'latest',
  },
  saveMissing: process.env.NODE_ENV !== 'production',
  saveMissingTo: 'current',
  partialBundledLanguages: true,
});

i18next.t('nav.signIn');

React SDK (lexisync-react)

npm install lexisync-react lexisync i18next react-i18next

import { LexiSyncProvider, useLexiSync, useT } from 'lexisync-react';

export function App() {
  return (
    <LexiSyncProvider
      projectId={import.meta.env.VITE_LEXISYNC_PROJECT_ID}
      apiUrl="https://lexisync.app"
      version="production"
      lng="en"
      ns={['common', 'marketing']}
      // apiKey + saveMissing only for local/dev against "latest"
    >
      <Page />
    </LexiSyncProvider>
  );
}

function Page() {
  const t = useT();
  const { changeLanguage, languages, status } = useLexiSync();
  return (
    <>
      <h1>{t('headline')}</h1>
      <select
        value={/* current lng */}
        onChange={(e) => void changeLanguage(e.target.value)}
      >
        {languages?.map((l) => (
          <option key={l.code} value={l.code}>{l.name || l.code}</option>
        ))}
      </select>
      <p className="text-xs opacity-60">{status}</p>
    </>
  );
}

Provider wires i18next + LexiSync backend, exposes language list (from CDN meta when available), reload, and status (loading / ready / error).

CDN

Public, Blob-backed JSON maps on a dedicated host — no API key, no database on the hot path. Floating tags (e.g. production) revalidate immediately after publish.

# Preferred (cdn.lexisync.app)
GET https://cdn.lexisync.app/{projectId}/{version}/{lng}/{namespace}.json
GET https://cdn.lexisync.app/{projectId}/{version}/languages

# Also on the app host
GET https://lexisync.app/cdn/{projectId}/{version}/{lng}/{namespace}

# Immutable content-hash URL (1y cache)
GET https://cdn.lexisync.app/{projectId}/immutable/{hash}/{lng}/{namespace}.json

# Examples
https://cdn.lexisync.app/cm_xxx/production/en/common.json
https://cdn.lexisync.app/cm_xxx/production/languages
https://lexisync.app/cdn/cm_xxx/latest/nl/auth

Response shape: flat object { "nav.signIn": "Sign in", ... }. npm packages default to https://cdn.lexisync.app when using the production API host.

HTTP API

Machine-first surface under /api/v1. Discover endpoints:

curl https://lexisync.app/api/v1
curl https://lexisync.app/api/v1/openapi.json

# Auth
curl -H "x-api-key: sk_…" https://lexisync.app/api/v1/me
# or: Authorization: Bearer sk_…

Client helpers

const {
  discoverApi,
  getMe,
  listLanguages,
  downloadCatalog,
  reportMissing,
  publishVersion,
} = require('lexisync/client');

const apiUrl = 'https://lexisync.app';
const apiKey = process.env.LEXISYNC_API_KEY;
const projectId = process.env.LEXISYNC_PROJECT_ID;

await getMe({ apiUrl, apiKey });
await listLanguages({ apiUrl, apiKey, projectId });
await downloadCatalog({ apiUrl, apiKey, projectId, version: 'production', format: 'nested' });
await reportMissing({
  apiUrl, apiKey, projectId,
  namespace: 'common', languageCode: 'en',
  keys: { 'cta.try': 'Try now' },
});
await publishVersion({ apiUrl, apiKey, projectId, version: 'production' });

Useful routes

API keys & security

• Secret sk_ — full write. CI secrets, server env, local CLI. Never ship to browsers in production.
• Public pub_ — read-only API. CDN often needs no key at all.
• Rotate keys from Settings if leaked.
• Prefer env vars over committing ~/.lexisync/config.json.

AI translate (Pro)

In the catalog editor, pick a target language and run Translate dirty. Only missing/empty strings (or AI-stale after source edits) are sent to GPT-5 nano via Vercel AI Gateway. Manual translations without an AI fingerprint are left alone.

• Max batch size per run (server-enforced).
• 60-second regeneration cooldown with progress bar.
• Free plan: feature locked — upgrade in Billing.

Errors

Package docs also ship on npm: lexisync · lexisync-react. API base: https://lexisync.app