---
title: "Set up the Action"
description: "Add the workflow, the API key and the triggers that keep a translations repository up to date."
canonical_url: "https://diglot.sh/workflow/action/setup"
---
# Set up the Action

> Add the workflow, the API key and the triggers that keep a translations repository up to date.

This page sets up the Action in a translations repository that already has a `diglot.config.ts`, a `sources.yml` and at least one locale. The finished workflow is in the [Nuxt example](https://diglot.sh/guide/examples/nuxt-translations).

## Enable machine translation for a locale

The Action drafts translations only for locales whose `<locale>/locale.yml` has `mt.enabled: true`:

```yaml [fr/locale.yml]
mt:
  enabled: true
```

Other locales get no new records, but their bundles are still rebuilt unless `build-dist` is `false`.

## Choose a model and add a key

Machine translation runs through the [Vercel AI Gateway](https://vercel.com/ai-gateway). Create a key, store it as the repository secret `AI_GATEWAY_API_KEY`, and pass it to the step as an environment variable, or use the `ai-gateway-api-key` input. Set the model with `mt.model` in `diglot.config.ts`, with the `model` input, or with the `DIGLOT_MT_MODEL` environment variable. The input takes precedence over the config.

## Write the workflow

The job needs write access to contents so that it can push:

```yaml [.github/workflows/translate.yml]
name: translate

on:
  workflow_dispatch:
  schedule:
    - cron: '23 4 * * *'

permissions:
  contents: write

concurrency:
  group: translate
  cancel-in-progress: false

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: diglot
        uses: danielroe/diglot/packages/action@main
        with:
          git-user-name: translations-bot
          git-user-email: translations-bot@users.noreply.github.com
        env:
          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
      - if: steps.diglot.outputs.committed == 'true'
        run: git pull --rebase origin ${{ github.ref_name }} && git push
        env:
          GIT_COMMITTER_NAME: translations-bot
          GIT_COMMITTER_EMAIL: translations-bot@users.noreply.github.com
```

The concurrency group makes a second run wait for the first, which prevents two jobs from drafting the same segments. The push step rebases first because translators may have pushed to the branch while the job was running.

## Trigger it when sources change

A schedule alone leaves translations up to a day behind. To run when a source repository changes, add a `repository_dispatch` trigger and have the source repository send it after a push that touches the docs:

```yaml
on:
  repository_dispatch:
    types: [source-push]
```

```bash
gh api repos/<owner>/<translations>/dispatches -f event_type=source-push -f 'client_payload[sources]=nuxt-main'
```

Pass `${{ github.event.client_payload.sources }}` to the `sources` input so the run refreshes only the sources that changed.

## The first run

On a new repository the first run has every segment to translate. Set the `limit` input to cap how many segments each locale sends to the model per run, and the rest wait for the next run. Cache `.diglot/checkouts` between runs so that the sources aren't cloned from scratch each time.

## Bundles

By default the Action builds `dist/<locale>.json` and commits it, forcing the files into the commit even when `dist` is git-ignored. Set `build-dist: 'false'` to leave bundles to another step, as the Nuxt example does.


## Sitemap

See the full [sitemap](https://diglot.sh/sitemap.md) for all pages.