> For the complete documentation index, see [llms.txt](https://developers.weglot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.weglot.com/frameworks-and-ai/translate-action.md).

# Translate Action

Translate your localization files from GitHub Actions with Weglot.

The [Weglot Translate Action](https://github.com/weglot/translate-action) translates the JSON localization files of your repository with your Weglot project. It writes the translated files to disk, or opens a pull request with them.

{% hint style="info" %}
The action requires a **Weglot 2.0** project. The full list of inputs and outputs is in the [action README](https://github.com/weglot/translate-action#inputs).
{% endhint %}

## Prerequisites

* A Weglot 2.0 project, with its source and target languages configured.
* The API key of this project, stored as a repository secret named `WEGLOT_API_KEY`.

## Quick start

Add the action after `actions/checkout`. Translated files are written next to the source file, for example `locales/fr.json` and `locales/de.json`:

```yaml
- uses: actions/checkout@v4
- uses: weglot/translate-action@v2
  with:
    api-key: ${{ secrets.WEGLOT_API_KEY }}
    source-path: locales/en.json
```

`source-path` also accepts a glob such as `locales/**/*.json`. Use `output-dir` to write the translations elsewhere, and `languages` (for example `fr,de,es`) to limit the target languages. By default, the action uses all the enabled languages of your project.

## Open a pull request with the translations

With `output-mode: pr`, the action pushes the translations to a `translations/<hash>` branch and opens or updates one pull request:

```yaml
permissions:
  contents: write
  issues: write
  pull-requests: write
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - uses: weglot/translate-action@v2
    with:
      api-key: ${{ secrets.WEGLOT_API_KEY }}
      source-path: locales/en.json
      output-mode: pr
      github-token: ${{ secrets.GITHUB_TOKEN }}
```

{% hint style="warning" %}
Pull request mode also requires **Allow GitHub Actions to create and approve pull requests** in your repository settings (**Settings → Actions → General → Workflow permissions**). Without it, the action pushes the branch but opens no pull request.
{% endhint %}

## Keep your repository in sync with the Weglot dashboard

Translations edited in the Weglot dashboard can come back to your repository in two ways:

* **On a schedule**: add a `schedule` trigger (and optionally `workflow_dispatch`) to a workflow in pull request mode. The action opens or updates the pull request only when translations changed.
* **On demand**: add an `issue_comment` trigger, then comment `/update` on the open translations pull request.

```yaml
on:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:
  issue_comment:
    types: [created]
```

## First run

Weglot 2.0 translates new strings with an LLM, through a queue. The first run can wait a little for the translations, up to `translation-timeout` (300 seconds by default). Translated strings are cached, so the next runs are immediate.

## Learn more

* [Action README](https://github.com/weglot/translate-action): all inputs, outputs and complete workflow examples.
* [Weglot 2.0](https://auth.weglot.com/): sign in and create your project.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.weglot.com/frameworks-and-ai/translate-action.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.