Large Projects

Lingo.dev CLI provides performance optimizations and workflow strategies for large-scale localization projects with hundreds of thousands of translation keys, multiple languages, and complex content structures.

For projects with extensive content, the CLI offers parallel processing and CI/CD integration to handle translation at scale efficiently.

Parallel Processing

Lingo.dev CLI processes large projects faster using parallel workers that handle multiple translation tasks simultaneously.

Enable parallel processing:

npx lingo.dev@latest run

This distributes translation tasks across multiple workers, significantly reducing processing time for large projects.

Control worker concurrency:

npx lingo.dev@latest run --concurrency 16

The default concurrency is 10 workers. Higher values process more tasks simultaneously but may hit API rate limits.

How Parallel Processing Works

The CLI creates a worker pool that processes translation tasks concurrently while preventing file corruption:

  1. Task distribution — Breaks down localization into individual tasks per locale and file
  2. Worker allocation — Assigns tasks to available workers using load balancing
  3. Race condition prevention — Uses file system locks to prevent conflicts when multiple workers access the same files
  4. Progress tracking — Reports real-time progress across all workers

Example for large projects:

// Project with 50 files across 10 languages = 500 translation tasks
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja", "zh", "ko", "pt", "it", "ru", "ar"]
  },
  "buckets": {
    "json": {
      "include": ["src/locales/[locale]/*.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

With parallel processing, these 500 tasks are distributed across workers instead of processing sequentially.

Targeted Processing

For large projects, you can process specific parts instead of everything at once:

Process specific languages:

npx lingo.dev@latest run --locale es --locale fr

Process specific file types:

npx lingo.dev@latest run --bucket json

Process specific files:

npx lingo.dev@latest run --file components/header

This selective processing is useful for incremental updates during development.

CI/CD Integration

Large projects benefit from automated translation workflows using GitHub Actions or other CI/CD systems.

GitHub Actions workflow:

name: Lingo.dev Localization
on:
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

This workflow processes translations on dedicated branches, keeping translation work separate from development.

Branch-Based Workflow

For large projects, use dedicated branches for translation work:

Create translation branch:

git checkout main
git checkout -b localize/content-update
# Make content changes
git push -u origin localize/content-update

Trigger translation via GitHub Actions:

  1. Navigate to repository Actions tab
  2. Select "Lingo.dev Localization" workflow
  3. Run workflow on your translation branch
  4. Review and merge translated content

This approach provides clear separation between content changes and translation processing.

Performance Considerations

System resources:

  • Parallel processing uses more CPU and memory
  • Monitor system performance with high concurrency settings
  • Cloud CI/CD runners handle parallel workloads efficiently

API rate limits:

  • Higher concurrency may trigger rate limiting
  • Start with default settings and adjust based on performance
  • Lingo.dev Engine handles rate limiting automatically

File system:

  • Large projects generate many translation files
  • Use .gitignore for temporary files if needed
  • Commit i18n.lock file for content tracking

Project Organization

Bucket separation:

{
  "buckets": {
    "app": {
      "include": ["src/locales/[locale].json"]
    },
    "marketing": {
      "include": ["marketing/[locale]/*.json"]
    },
    "docs": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Separate buckets allow targeted processing of different content areas.

File structure:

project/
  src/locales/           # Application content
  marketing/             # Marketing content
  docs/                  # Documentation
  i18n.json             # Configuration
  i18n.lock             # Content tracking

Organized structure makes large projects manageable and enables selective processing.

Scaling Strategies

Incremental processing:

  • Use lockfile to process only changed content
  • Update specific languages or buckets as needed
  • Combine with CI/CD for automated incremental updates

Team workflows:

  • Use branch-based translation for collaboration
  • Separate content changes from translation work
  • Review translations before merging to production

Resource optimization:

  • Adjust concurrency based on system capabilities
  • Use cloud runners for heavy processing workloads
  • Monitor processing times and optimize bucket configurations