Organize CLI v0 in a monorepo

Choose shared or per-package configuration and keep each legacy output tied to its own source baseline.

Use one root i18n.json when packages share source language, target languages, and translation backend. Use per-package files when they need independent policy or ownership. Each configuration has its own i18n.lock.

Discover a shared layout from the root configuration #

From 0.135.0, recursive patterns can discover matching packages:

json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": { "source": "en", "targets": ["es", "fr"] },
  "buckets": {
    "json": { "include": ["apps/**/locales/[locale].json"] }
  }
}

A new package joins only if its path matches. Inspect discovery after adding it, and exclude generated or internal content that should not be sent for translation. The default exclusions cover common build directories, not every project-specific tree.

Older releases and varied layouts can list paths explicitly:

json
{
  "locale": { "source": "en", "targets": ["es", "fr"] },
  "buckets": {
    "json": {
      "include": [
        "apps/web/locales/[locale].json",
        "apps/dashboard/locales/[locale].json"
      ]
    },
    "markdown": { "include": ["packages/docs/content/[locale]/*.md"] }
  }
}

Both layouts share one root lockfile and backend choice. Do not run independent processes against that state at the same time.

Separate packages with different policy #

Place i18n.json inside each package that needs independent targets or a different localization engine. Select engineId explicitly. Packages can share a localization engine while asking for different language pairs.

Run from the owning directory:

sh
cd apps/web
lingo run

Commit that package's source, accepted output, configuration, and lockfile together. Check its own application or documentation build; shared translation instructions do not establish that each package loads the generated files.

Keep the CI package list explicit #

A matrix can enumerate working directories, each invoking the pinned legacy binary beside its i18n.json. Adding a package to the repository does not add it to an explicit matrix.

The workflow pins the Lingo.dev Action separately from lingo.dev@0.138.10. Save LINGODOTDEV_API_KEY as a repository secret for translation and allow Actions to create pull requests in the repository settings. GH_TOKEN supplies the separate GitHub credential.

yaml
name: Translate legacy packages
on:
  workflow_dispatch:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
concurrency:
  group: legacy-translations-${{ github.ref }}
  cancel-in-progress: false
jobs:
  translate:
    runs-on: ubuntu-latest
    strategy:
      max-parallel: 1
      fail-fast: false
      matrix:
        package: [apps/web, apps/marketing]
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: "22"
      - uses: lingodotdev/lingo.dev@0050b4858e1cea2b745c8f131fe178a23f643dc7
        with:
          version: "0.138.10"
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          working-directory: ${{ matrix.package }}
          pull-request: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Each package needs its own committed i18n.json, source files, accepted targets, and i18n.lock. For a shared root configuration, change the matrix to package: ["."]; recursive source patterns can then discover packages under that one configuration.

The legacy Action uses a translation branch for the base branch, so package jobs are serialized to update the same pull request. Keep the concurrency group shared with other workflows that use that translation branch. Review output for every package in the PR, including after reruns, and run each package's resource checks before merging.

If GitHub marks the PR workflows as awaiting approval, a repository writer must choose Approve workflows to run. See GitHub's GITHUB_TOKEN behavior.