Skip to main content
With a GitHub Action, new translations arrive in your repository as a pull request on their own. The trigger is the language.completed webhook: Tolk sends it as soon as a language is 100% translated. The workflow also runs on a schedule and by hand, so nothing is left behind even without the webhook.

How it works

GitHub starts a workflow from outside with a repository_dispatch. That requires a GitHub token and its own format, so Tolk cannot call the GitHub API directly. A small relay in between verifies Tolk’s signature and starts the workflow. Without a relay the workflow works too, just only on the schedule and by hand.

1. Token in GitHub

1

Create a token in Tolk

Under Settings › API tokens (Instellingen › API-tokens), create a token with Read only (Alleen lezen), named “GitHub Actions”.
2

Secret in GitHub

Add the token to the repository (or the organization) as the secret TOLK_TOKEN.
3

Allow pull requests

In the repository, under Settings › Actions › General, turn on Allow GitHub Actions to create and approve pull requests.

2. The workflow

Put this file in .github/workflows/tolk-pull.yml. Set TOLK_PROFILE to the export profile you want to fetch (GET /v1/project lists them under exportProfiles).
.github/workflows/tolk-pull.yml
  • If there are no changes, the action opens no pull request.
  • An existing pull request on tolk/translations is updated, so you never get more than one at a time.
As soon as the Laravel package is available, replace the Fetch export step with composer install and php artisan tolk:pull.

3. The relay for language.completed

The relay is a small endpoint, for example a serverless function. It verifies Tolk’s signature and starts the workflow. The example uses Node 20 or newer.
relay.mjs
Then, in Tolk under Settings › Webhooks, add a webhook with the URL of the relay and the language.completed event. Use Send test (Test versturen) to check that the relay is reachable: a ping starts no workflow, but the relay responds 204.
The relay responds within a few seconds. Tolk waits at most 5 seconds for a response and then retries. A duplicate delivery is harmless: the workflow then updates the same pull request.