lgtm-translate

Client SDK for LGTM-translate — AI-powered internationalization. One package handles build-time string extraction, runtime translation delivery, and CI/CD manifest sync.

Setup (Next.js)

1. Install

npm install lgtm-translate

2. Add the build plugin

// next.config.js
const { withLgtmTranslate } = require('lgtm-translate/plugin');

module.exports = withLgtmTranslate({
  // your existing Next.js config
});

The plugin scans JSX at build time:

• Detects user-facing text and generates content-based IDs (project_7f3a)
• Injects data-lgtm-translate attributes on elements
• Extracts t() calls and @lgtm-translate annotated objects/arrays
• Writes the lgtm-translate.json manifest

3. Wrap your app with the provider

// app/layout.tsx
import { LgtmTranslateProvider } from 'lgtm-translate';

export default function RootLayout({ children }) {
  return (
    <LgtmTranslateProvider project="my-app" defaultLocale="en">
      {children}
    </LgtmTranslateProvider>
  );
}

The provider detects the user's language, fetches translations from the LGTM-translate server, and swaps element text via data-lgtm-translate attributes.

4. Use t() for dynamic strings

import { t } from 'lgtm-translate';

// Static JSX text is auto-detected — no t() needed
<button>Cancel</button>

// Use t() for strings the AST can't trace
const msg = t("Something went wrong");
const cart = t("{count:number} items in your cart");

5. Sync manifest in CI/CD

LGTM_API_KEY=lgtm_sk_... npx lgtm-translate sync

Reads lgtm-translate.json, authenticates with the server, and uploads new/changed strings for translation.

Features

• Auto-detection — hardcoded JSX strings and ternaries are extracted without any developer annotation
• Content-based IDs — same text = same ID = one translation shared everywhere
• Variable interpolation — {userName} placeholders preserved across all languages
• CLDR plural rules — {count:number} triggers plural form generation for 40+ locales
• Human overrides — AI translations are never overwritten once a human edits them
• Text change detection — changing element text automatically generates a new ID; no manual ID management

Development

Prerequisites

• Node.js 22+
• npm

Install dependencies

cd sdk
npm install

Run tests

npx vitest run

Type check

npx tsc --noEmit

Build

npx tsc

Output goes to dist/.

Package Structure

sdk/
├── src/
│   ├── index.ts                  # Main exports: LgtmTranslateProvider, t(), useTranslation
│   ├── plugin/
│   │   ├── index.ts              # Plugin exports: withLgtmTranslate
│   │   ├── babel-plugin.ts       # Babel AST visitor — scans JSX, extracts strings, injects IDs
│   │   ├── id-generator.ts       # Content-based ID hashing (project prefix + CRC)
│   │   ├── manifest.ts           # Reads/writes lgtm-translate.json manifest
│   │   └── with-lgtm-translate.ts # Next.js config wrapper (adds Babel loader via webpack)
│   ├── runtime/
│   │   ├── provider.tsx          # LgtmTranslateProvider — fetches translations, swaps DOM text
│   │   ├── t.ts                  # t() function — build-time extraction + runtime lookup
│   │   ├── plurals.ts            # CLDR plural category selection
│   │   ├── interpolate.ts        # Variable interpolation ({name} → value)
│   │   ├── locale.ts             # Browser locale detection + fallback
│   │   └── id-generator-browser.ts # Browser-compatible ID generator (Web Crypto API)
│   └── cli/
│       ├── bin.ts                # CLI entry point (npx lgtm-translate <command>)
│       └── sync.ts               # Manifest upload — reads JSON, authenticates, POSTs to server
├── __tests__/
│   ├── plugin/                   # Plugin unit tests (Babel transforms, ID generation, manifest)
│   ├── runtime/                  # Runtime unit tests (provider, t(), plurals, interpolation)
│   ├── cli/                      # CLI unit tests (sync command)
│   └── exports.test.ts           # Package export validation
├── dist/                         # Compiled output (tsc)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Full Spec

See docs/LGTM-translate_Shared_Translations_Spec.md for the complete product specification including ID generation rules, shared translation flow, text change handling, cleanup, caching strategy, and auth model. (Note: the spec filename retains its original name.)