GitHub Integration

The GitHub integration keeps localization files in sync between a GitHub repository and your Localizely project, so developers and translators can each work in the tool they know without passing files around by hand.

It works in both directions. Localizely pulls localization files from the repository, either on demand or automatically through a webhook whenever your team pushes code. When translations are ready, Localizely pushes them back by opening a pull request in your repository, so the updated files go through your normal review before they are merged.

Setup

1. Add a localizely.yml file to your repository

The integration reads a localizely.yml configuration file from your repository to learn which files to pull from GitHub and which files to push back. Here is a minimal configuration for a Flutter project:

config_version: 1.0 # Only 1.0 available
project_id: 33d9e1a5-6ba8-4b36-a354-47389c432f42 # Your project ID from: https://app.localizely.com/projects
file_type: flutter_arb
upload:
  files: # List of files for upload to Localizely. Usually it is just one file used for the main locale
    - file: lib/l10n/intl_en.arb
      locale_code: en
download:
  files: # List of files for download from Localizely.
    - file: lib/l10n/intl_en.arb
      locale_code: en
    - file: lib/l10n/intl_de.arb
      locale_code: de
    - file: lib/l10n/intl_es.arb
      locale_code: es

The configuration file page covers every available option, including other file formats.

2. Create a GitHub access token

Localizely authenticates with GitHub using a personal access token. On GitHub, click your avatar in the top-right corner and go to Settings > Developer settings > Personal access tokens. Click Generate new token and create a classic token with the repo scope.

A fine-grained personal access token works too. In that case, add your repository under Repository access and, under Repository permissions, grant Read and write access to both Contents and Pull requests.

Copy the token as soon as it is generated. GitHub shows it only once.

3. Connect your repository

In Localizely, the project owner and project admins connect the repository. Open the project's Settings page and select GitHub Integration in the Integrations section, then:

Your access token is stored encrypted and is never shown in full again after you save it.

Pulling files from GitHub

Manual pull

On the project's Settings page, open Integrations > GitHub and click Pull now. Localizely reads the files listed in the upload section of your configuration and imports any new or changed strings.

Automatic pull

Once a manual pull works, set up a webhook so Localizely pulls automatically every time code is pushed to the connected branch. New strings reach your translators minutes after a developer commits them, with no one having to remember to sync.

In GitHub, open your repository's Settings > Webhooks and click Add webhook. Copy the Webhook payload URL and Webhook secret from the integration details in Localizely into the Payload URL and Secret fields. Set the content type to application/json, keep Just the push event selected, and save the webhook.

Pushing files to GitHub

When the translations are ready, open Integrations > GitHub on the project's Settings page and click Push now. Localizely then:

Your team reviews and merges the pull request on GitHub like any other change. Localizely never commits directly to the connected branch.

Frequently asked questions

Can I link one Localizely project to several repositories?

This integration connects a Localizely project to a single GitHub repository. To keep additional repositories in sync with the same project, use the CLI or the REST API.