Monorepos

La CLI ofrece compatibilidad nativa con monorepos. Puedes usar un único i18n.json en la raíz con un glob recursivo ** para detectar automáticamente los paquetes, una única configuración en la raíz con rutas explícitas por paquete, o archivos i18n.json independientes en cada paquete combinados con una GitHub Action con estrategia de matriz.

Cuándo usar cada patrón#

Patrón 1: Configuración única recursiva#

Cuando todos los paquetes siguen la misma estructura (por ejemplo, apps/<name>/locales/[locale].json), usa un glob recursivo ** en un único i18n.json en la raíz. Los nuevos paquetes se detectarán automáticamente siempre que encajen en esa estructura:

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

La CLI ignora node_modules, .git, dist, build, .next y .turbo por defecto, así que los patrones recursivos no bajarán a árboles vendorizados ni de compilación. Añade tus propias entradas exclude para cualquier otro elemento que quieras omitir.

La GitHub Action es idéntica al patrón 2 de abajo: un paso, con el directorio de trabajo por defecto.

Úsalo cuando todos los paquetes compartan el mismo idioma de origen, los mismos idiomas de destino, la misma estructura y el mismo motor de localización, y no quieras editar i18n.json cada vez que añadas un paquete.

Patrón 2: Configuración única, idiomas compartidos#

Un i18n.json en la raíz del repositorio. Las rutas de los buckets apuntan explícitamente a cada paquete:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": [
        "apps/web/locales/[locale].json",
        "apps/dashboard/locales/[locale].json"
      ]
    },
    "markdown": {
      "include": ["packages/docs/content/[locale]/*.md"]
    }
  }
}

GitHub Action: paso único estándar:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          pull-request: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Úsalo cuando todos los paquetes compartan el mismo idioma de origen, los mismos idiomas de destino y el mismo motor de localización, pero las estructuras sean lo bastante distintas como para que un glob recursivo resulte demasiado amplio.

Patrón 3: Configuraciones por paquete, distintos idiomas#

Cada paquete tiene su propio i18n.json con idiomas de destino independientes:

apps/web/i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja", "ko", "zh-Hans"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

apps/marketing/i18n.json:

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

GitHub Action: estrategia de matriz con working-directory:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package: [apps/web, apps/marketing]
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          working-directory: ${{ matrix.package }}
          pull-request: true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Cada entrada de la matriz ejecuta la CLI limitada al i18n.json de ese paquete. La acción traduce solo los archivos que declare ese paquete.

Patrón 4: Configuraciones por paquete, motores independientes#

La estructura es la misma que en el patrón 3, pero cada paquete se conecta a un motor de localización distinto. Así, cada paquete tiene su propio glosario, voz de marca y configuración de modelo.

apps/product/i18n.json:

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

apps/docs/i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  },
  "buckets": {
    "markdown": {
      "include": ["content/[locale]/*.md"]
    }
  },
  "engineId": "eng_DocsEngine456"
}

El YAML de la GitHub Action es idéntico al del patrón 3: el engineId de cada i18n.json dirige automáticamente las traducciones al motor correcto.

Cómo funciona el lockfile#

Cada ubicación de i18n.json genera su propio archivo i18n.lock en el mismo directorio. El lockfile registra qué contenido fuente ya se ha traducido, lo que permite actualizaciones incrementales. En los patrones 1 y 2 hay un único lockfile en la raíz. En los patrones 3 y 4, cada paquete tiene el suyo.

Preguntas frecuentes#

¿Los nuevos paquetes se detectarán automáticamente?

Solo con el patrón 1 (** recursivo). Con los patrones 3 y 4, tendrás que añadir una nueva entrada a la lista matrix.package del flujo de trabajo cuando incorpores un paquete.

¿Puedo tener distintos idiomas por paquete?

Sí. Usa el patrón 3 o el 4. El i18n.json de cada paquete declara su propia matriz locale.targets de forma independiente.

¿Necesito un archivo de flujo de trabajo o varios?

Un único archivo de flujo de trabajo con estrategia de matriz basta para todos los paquetes. Cada entrada de la matriz se ejecuta sobre un working-directory distinto, limitando la CLI a la configuración de ese paquete.

¿Pueden los paquetes compartir un glosario y tener idiomas distintos?

Sí. Haz que ambos paquetes apunten al mismo engineId, pero configura distintos locale.targets en cada i18n.json. El glosario del motor se aplicará a los pares de idiomas que se soliciten.

Siguientes pasos#