GitHub Integration



Use this integration to synchronize translation files between your GitHub repository and Localizely project.

Once you configure the integration, you can pull the files from GitHub by using the Localizely web console. Pull can be automated via webhooks so it is triggered whenever new code changes are pushed to GitHub by your development team.

When the translations are done, you can push the translations to GitHub by creating a pull request.


1. Create localizely.yml file

GitHub integration relies on the localizely.yml configuration file in your GitHub repository, so Localizely knows what files to synchronize. This file defines which files you want to import (pull) from and export (push) to GitHub.

Here is a minimal configuration file for Flutter projects:

config_version: 1.0 # Only 1.0 available
project_id: c776c33e-f428-4c91-87e1-a6a18c1554fe # Your project ID from:
file_type: flutter_arb
  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
  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

See the documentation to learn more about how to set up your Localizely configuration file.

2. Create GitHub access token

You will need to generate and copy/paste a personal access token from GitHub. Navigate to, click on your avatar in the top right corner, and choose Settings > Developer settings > Personal access tokens. Next, click Generate new token to generate a new (classic) access token. Make sure the token has the repo scope.

In addition to the regular (classic) token, you can also use a fine-grained personal access token. If you opt for this type of token, ensure your repository is in the Repository access section, and the token's Repository permissions allow "Read and write" access for Contents and Pull requests.

Once you have generated the access token, make sure to copy it.

3. Connect your repository

Go to the settings for the Localizely project and select GitHub Integration under the Integrations section.

  • Paste your GitHub access token you previously created.
  • Choose the GitHub repository you want to sync with Localizely.
  • Choose the repository branch you want to import (pull) from and export (push) to. Usually, this is the “main” branch.
  • Click Validate Configuration to check if your access token and configuration file are set up correctly.
  • Click Save.
GitHub configuration dialog

Your access token is safe, it is stored in an encrypted form in our system.

Pulling files from GitHub

Manual Pull

Go to Project Settings > Integrations > GitHub, and click the Pull now button.

GitHub configuration details


Once you make Pull works, it is practical to set up a webhook in GitHub which automates pulling the changes to Localizely as you push code changes to GitHub.

In GitHub, navigate to your repository Settings > Webhooks and copy/paste the Webhook payload URL and Webhook secret provided in the Localizely integration configuration.

GitHub webhook setup

Pushing files to GitHub

When the translations are completed, go to Project Settings > Integrations > GitHub, and click the Push now button.

The Push will do the following:

  1. A new branch is created from the last revision of the branch you chose in the integration setup. The branch name would look like this: localizely_2021-01-10_13-15-10.
  2. A commit with updated translation files is created in the new branch.
  3. A pull request from the new branch to the previously chosen branch is created.

You may then review and merge the pull request at GitHub.

Frequently Asked Questions (FAQ)

How to link Localizely project to multiple git repositories?

One Localizely project can be directly linked to one GitHub repository via this integration. However, you can use other integrations such as CLI or REST API to link with additional repositories.

Tired of manually editing translation files?

Our platform streamlines software localization for you.

Copyrights 2024 © Localizely