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

# GitHub Actions

> Automatically translate files in your repository using GitHub Actions

The honyaku.dev GitHub Action translates your source file into multiple target languages and commits the results back to your repository.

## Setup

<Steps>
  <Step title="Get an API key">
    Generate an API key from the [settings page](https://honyaku.dev/settings).
  </Step>

  <Step title="Add the API key to your repository">
    Go to your repository's **Settings > Secrets and variables > Actions** and create a new secret named `HONYAKU_API_KEY` with your API key.
  </Step>

  <Step title="Create a workflow file">
    Create `.github/workflows/translate.yml` in your repository:

    ```yaml theme={null}
    name: Translate

    on:
      push:
        branches: [main]
        paths:
          - "messages/en.json"
      workflow_dispatch:

    permissions:
      contents: write

    jobs:
      translate:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: honyaku-dev/honyaku-action@v1
            with:
              source-file: "messages/en.json"
              output-dir: "messages/generated"
              targets: "ja:ja.json, zh:zh.json, ko:ko.json"
              api-key: ${{ secrets.HONYAKU_API_KEY }}
    ```
  </Step>
</Steps>

## Inputs

| Name            | Required | Default                      | Description                                                            |
| --------------- | -------- | ---------------------------- | ---------------------------------------------------------------------- |
| `source-file`   | Yes      |                              | Path to the source translation file                                    |
| `output-dir`    | Yes      |                              | Output directory for translated files                                  |
| `targets`       | Yes      |                              | Comma-separated list of target locales in `<locale>:<filename>` format |
| `api-key`       | Yes      |                              | API key for authentication                                             |
| `translator-id` | No       | `gpt_4_1_mini`               | Translator model ID                                                    |
| `custom-prompt` | No       | `""`                         | Custom prompt for the translator                                       |
| `base-url`      | No       | `https://honyaku.dev/api/v1` | Base URL of the Honyaku API                                            |

## Custom Prompts

You can use the `custom-prompt` input to give the translator additional context about your project:

```yaml theme={null}
- uses: honyaku-dev/honyaku-action@v1
  with:
    source-file: "messages/en.json"
    output-dir: "lang"
    targets: "ja:ja.json, zh:zh.json, ko:ko.json"
    api-key: ${{ secrets.HONYAKU_API_KEY }}
    custom-prompt: "Translate for a casual mobile game UI"
```

## Lock File

The action creates a `honyaku-lock.json` file in your repository root to track the analysis history. Commit this file to your repository. It enables incremental processing by linking new analyses to previous ones.

To avoid unnecessary runs, use the `paths` filter in your workflow trigger to only run the action when the source file changes (see the example workflow above).

## How It Works

1. Uploads the source file to the Honyaku API.
2. Decompiles the file to extract translatable strings (using the previous analysis history from `honyaku-lock.json` if available for incremental processing).
3. Queues translation jobs for each target locale.
4. Polls for job completion.
5. Downloads the translated files and extracts them to the output directory.
6. Updates `honyaku-lock.json` and commits/pushes the changes.