Skip to main content
LazyLocales uses a configuration file at the root of your project. It is created automatically on your first lazylocales translate run, or you can create it manually.

​
Config file

The CLI looks for one of these files (in order):
  1. lazylocales.config.ts
  2. lazylocales.config.js
  3. lazylocales.config.json
lazylocales.config.ts
import { defineConfig } from 'lazylocales';

export default defineConfig({
  projectId: 'proj_abc123',
  localesDir: './public/locales',
  sourceLocale: 'en',
});

​
JSON

lazylocales.config.json
{
  "projectId": "proj_abc123",
  "localesDir": "./public/locales",
  "sourceLocale": "en"
}

​
Options

OptionTypeRequiredDescription
projectIdstringYesYour LazyLocales project ID (e.g. proj_abc123)
localesDirstringYesRelative path to your locales directory
sourceLocalestringYesBCP 47 code of your source language (e.g. en)
apiTokenstringNoAPI token for CI/CD (overrides login session)

​
Using API tokens for CI/CD

For non-interactive environments (CI pipelines, servers), set the apiToken option:
lazylocales.config.ts
import { defineConfig } from 'lazylocales';

export default defineConfig({
  projectId: 'proj_abc123',
  localesDir: './public/locales',
  sourceLocale: 'en',
  apiToken: process.env.LAZYLOCALES_API_TOKEN,
});
If you add an apiToken to the config, add the config file to your .gitignore to avoid leaking the token. Alternatively, always use an environment variable as shown above.

​
Context keys

You can provide translation context by adding __context__ keys to your source JSON. These keys are sent to the AI but are not included in the translated output.
en.json
{
  "greeting": "Hello",
  "__context__greeting": "Informal greeting shown on the homepage hero section",
  "cta.start": "Get started",
  "__context__cta.start": "Call-to-action button, keep it short (max 2 words)"
}
Context keys help the AI produce more accurate translations by understanding where and how each string is used.