> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Automate translation syncing with GitHub Actions.

Integrate Entri into your GitHub Actions pipeline to automatically push new source strings and pull translations on every relevant commit. The `nt3` CLI supports non-interactive authentication and machine-readable JSON output designed for CI environments.

## Prerequisites

* An Entri API token (generate one in **Settings → API Tokens**)
* A `.nt3.yml` config file committed to your repository
* The `nt3` CLI installed globally in your workflow

## Store your API token

Add your Entri API token as a repository secret:

1. Go to your GitHub repository → **Settings → Secrets and variables → Actions**
2. Click **New repository secret**
3. Name it `NT3_TOKEN` and paste your API token

## Basic workflow: push on source change

This workflow runs whenever your source locale file changes. It pushes updated strings to Entri so translators and AI can act on them immediately.

```yaml theme={null}
name: Sync Translations

on:
  push:
    branches:
      - main
    paths:
      - 'src/locales/en.json'

jobs:
  push-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Push source strings to Entri
        run: |
          npm install -g nt3
          nt3 login -t ${{ secrets.NT3_TOKEN }}
          nt3 push --json
```

## Full sync workflow: push and pull

For projects that want to keep translated files up to date in the repository, use a full push-pull cycle and commit the results back.

```yaml theme={null}
name: Sync Translations

on:
  push:
    branches:
      - main
    paths:
      - 'src/locales/en.json'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Entri CLI
        run: npm install -g nt3

      - name: Authenticate
        run: nt3 login -t ${{ secrets.NT3_TOKEN }}

      - name: Push source strings
        run: nt3 push --json

      - name: Pull translations
        run: nt3 pull --json

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/locales/
          git diff --staged --quiet || git commit -m "chore: update translations from Entri"
          git push
```

<Note>
  The `git diff --staged --quiet || git commit` pattern only creates a commit when there are actual changes, preventing empty commits when translations are already up to date.
</Note>

## Scheduled AI translation

Run AI translation on a schedule to automatically translate new strings overnight.

```yaml theme={null}
name: Auto-translate

on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM UTC daily
  workflow_dispatch:       # Allow manual trigger

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Entri CLI
        run: npm install -g nt3

      - name: Authenticate
        run: nt3 login -t ${{ secrets.NT3_TOKEN }}

      - name: Translate all languages with AI
        run: nt3 translate --all --json

      - name: Pull updated translations
        run: nt3 pull --json

      - name: Commit results
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/locales/
          git diff --staged --quiet || git commit -m "chore: AI translations from Entri"
          git push
```

## CLI flags reference

| Flag                          | Purpose                                                 |
| ----------------------------- | ------------------------------------------------------- |
| `nt3 login -t <token>`        | Non-interactive authentication for CI                   |
| `nt3 push --json`             | Push source strings; output machine-readable JSON       |
| `nt3 pull --json`             | Pull all target languages; output machine-readable JSON |
| `nt3 pull -l fr --json`       | Pull a specific language only                           |
| `nt3 translate --all --json`  | AI-translate all untranslated keys                      |
| `nt3 push --overwrite --json` | Push and overwrite existing translations                |

## Exit codes

The CLI exits with `0` on success and a non-zero code on failure, so any step failure automatically fails the workflow job. Use `--json` to capture structured output for downstream steps or notifications.

## Multiple file patterns

If your `.nt3.yml` defines multiple file patterns (for example, separate namespace files), `push` and `pull` handle all patterns automatically — no extra configuration is needed in the workflow.

```yaml theme={null}
# .nt3.yml
project_id: "proj_abc123"
source_language: en
file_patterns:
  - path: "src/locales/{lang}/common.json"
    format: json-nested
  - path: "src/locales/{lang}/auth.json"
    format: json-nested
```