Build-time translations

Generate translations during your build process instead of committing them to git. Only the source language file lives in your repository — all target languages are created fresh on every build, eliminating translation-related merge conflicts entirely.

Why build-time? On large teams, translation files cause constant merge conflicts because every branch touches the same locale files. With build-time translations, autoglot is the source of truth and generates translations on demand — your git history stays clean.

How it works

en.jsoncommitted to git (source of truth)

autoglot translates during build

es.json fr.json de.jsongenerated, gitignored

app bundles translations at runtime

Translation script

Use @autoglot/cli as a library in a build script for full control:

javascript

// scripts/translate.mjs
import { translate } from '@autoglot/cli';
import { readFileSync, writeFileSync, mkdirSync } from 'fs';
import { resolve, dirname } from 'path';

const SOURCE_FILE = 'src/locales/en.json';
const TARGET_LANGUAGES = ['es', 'fr', 'de', 'ja', 'pt'];

// Translate fewer languages on preview deployments
const isPreview = process.env.VERCEL_ENV === 'preview';
const languages = isPreview ? ['es'] : TARGET_LANGUAGES;

const sourcePath = resolve(SOURCE_FILE);
const content = readFileSync(sourcePath, 'utf-8');

const files = await translate({
  files: [{ filename: 'en.json', content }],
  targetLanguages: languages,
  sourceLanguage: 'en',
  apiKey: process.env.AUTOGLOT_API_KEY,
  project: 'myorg/my-app',
  timeoutSeconds: 120, // fall back to the latest compatible cached artifact
  onProgress: (status) => {
    if (status.total_strings > 0) {
      console.log(`${status.completed_strings}/${status.total_strings}`);
    }
  },
});

const outputDir = dirname(sourcePath);
for (const file of files) {
  writeFileSync(resolve(outputDir, file.filename), file.content, 'utf-8');
}

Add to your build

json

{
  "scripts": {
    "translate": "node scripts/translate.mjs",
    "build": "node scripts/translate.mjs && next build"
  }
}

Gitignore generated files

Gitignore all locale files except the source language:

yaml

# .gitignore
src/locales/*.json
!src/locales/en.json

Turborepo setup

If using Turborepo, add AUTOGLOT_API_KEY to your task environment and make build depend on translate:

json

{
  "tasks": {
    "translate": {
      "env": ["AUTOGLOT_API_KEY"]
    },
    "build": {
      "dependsOn": ["translate"],
      "env": ["AUTOGLOT_API_KEY"]
    }
  }
}

Preview optimization

Translating all languages on every preview deploy can be slow. Translate into one language on previews and all languages on production:

javascript

const isProduction = process.env.VERCEL_ENV === 'production';
const languages = isProduction
  ? ['es', 'fr', 'de', 'ja', 'pt', 'zh', 'it', 'nl']
  : ['es'];  // one language on preview to save time