Skip to main content
GitHub

Pull files from GitHub and create pull requests from Lokalise.

Nick Ustinov avatar
Written by Nick Ustinov
Updated over 4 months ago

Use this app to exchange files with your GitHub repository

Once the app is set up, you can manually pull files through the Lokalise web dashboard or set up automatic pulls, so files are imported automatically when pushed to GitHub by your dev team.

When translations are done, you can trigger a pull request on GitHub from the Download page.

Setup

This app is available only for Web and mobile projects.

1. Connect your repository

Open your Lokalise project and navigate to Apps.

Find GitHub in the list of apps, click on it, press Install, and then Connect.

You used to need a special access token from GitHub, but now it's all done through OAuth 2. You can still use personal access tokens for existing setups, but new ones use OAuth. Just click Connect and give Lokalise Apps the needed access rights. The repo scope is required.

If you're connecting Lokalise to a GitHub organization (not a personal account), you might need to follow extra steps. Check the Note on GitHub organization section for details.

Enter the Repository name (prefixed with your organization name) and the Branch to pull from:

As you export files from Lokalise, you can set the GitHub app to create pull requests to repos matching the exported file format.

Decide if you want filenames to include a full path. Usually, you don’t need it since you can set the directory structure prefix during pull request creation. But if you have similar files in different subfolders (e.g., admin/locale.json and frontend/locale.json), enable the Include path in filenames option. Note that if you already have files uploaded, including a path in filenames here means you're uploading different files.

2. Select files to pull

Usually, you'll just need to select the base language files (the ones being modified locally and then pushed to GitHub).

Look through the selected repository and choose the files you want to pull and import.

After selecting a file, choose the language of the file from the dropdown menu:

Once the files are pulled, you can find your translation data in the Editor:

3. Add more repositories

If you want to keep all platform files in the same project, you might need to set up other repositories related to the same project. Click Add another repo to add more repositories.


Note on GitHub organizations

If you're connecting Lokalise to a GitHub organization and encounter errors after logging in and granting access, follow these steps:

  • Find your organization in the Organization access section and click Grant:

  • Open your organization settings at this URL: https://github.com/organizations/YOUR_ORGANIZATION_NAME/settings/oauth_application_policy (this is found under Organization settings > Integrations > Third-party access).

  • Ensure that Lokalise Apps is approved. If not, click the pen icon and manually set the status to "approved".

After completing these steps, return to the Setup section and try connecting your repository again.


Pulling files

Manual pull

se the Pull now button on the app page. Clicking this button adds the pull to the system queue to be executed in the background.

If you need to adjust options, click Pull options on the app page. These options are similar to those on the Upload page.

Auto-pull

Once you're satisfied with the initial pull results, set up a webhook in GitHub to automate pulling changes to Lokalise as you push to GitHub.

  • Open GitHub and navigate to your repository settings > Webhooks

  • Copy/paste the Auto-pull URL provided in the Lokalise app configuration into the Payload URL field

  • Provide the Auto-pull secret generated on Lokalise and paste it into the Secret field

  • Tick the Enable SSL verification option

  • Choose Just the push event for the Which events would you like to trigger this webhook? setting

  • Make sure to tick the Active setting

  • Click Add webhook

We're migrating all auto-pull URLs from app.lokalise.com to api.lokalise.com. The app page might still show app.lokalise.com, but it's recommended to use api.lokalise.com when pasting to GitHub.


Pull requests

To create a new pull request on GitHub with all the changes made on Lokalise, go to the Download page and find the App triggers section. Enable the GitHub option:

Use the Preview button first to see the resulting file/folder structure before triggering the creation of a pull request:

We recommend triggering pull requests only to repos matching the file type you're exporting (e.g., JSON format for Web platform repos).

Press Build only to create the pull request without downloading a translation bundle to your local PC. To check the status of the pull request creation, return to the GitHub app page and click the Logs button.

Here's what happens after triggering a new PR:

  • A new branch is created from the last revision of the branch chosen in the app setup. The branch name looks like this: lokalise-2018-03-12_15-14-13.

  • A commit with all the files is created in the new branch.

  • A pull request from the new branch to the previously chosen branch is created.

  • You can then review and merge the pull request on GitHub.

API

To initiate a pull request from the API, use triggers=['github'] parameter with the /export endpoint. For the CLI tool, use --triggers=github as a parameter when performing the export.


GitHub Enterprise

This app is available from the Pro plan and above.

This app allows you to exchange files with a self-hosted GitHub Enterprise. You'll need to provide a URL to the server where your GitHub is hosted and a personal token when setting up the app.

To generate a personal access token:

  • Open GitHub.

  • Click on your avatar and choose Settings.

  • In the left sidebar, click Developer settings.

  • In the left sidebar, click Personal access tokens.

  • Click Generate new token.

  • Give your token a descriptive name.

  • Enable the repo scope for this token.

  • Click Generate token, copy it and paste to the corresponding field on Lokalise. Never publicly expose your token!

Apart from that, this feature works the same way as the regular GitHub app.


FAQ

Why does Lokalise request access to all my repositories?

Lokalise requests access to all repositories to list them during setup so you can specify which repository to connect to Lokalise. There is no more restrictive OAuth scope for this purpose. Once the app is configured, Lokalise only works with the repository you selected. Admin scopes are not required.

What actions does the app use the OAuth token for?

Lokalise only creates merge requests and fetches the files you selected during setup. The Lokalise GitHub app does not alter the repo’s settings.

Is there any way to restrict the app's permissions?

GitHub user permission scopes limit access for OAuth tokens. The Lokalise app’s access is limited by the permissions of the user who configures the integration. If you need to limit the integration’s access to a specific repository, you can do so by limiting the permissions of the authorizing user’s GitHub account.

GitHub users can always revoke a token or edit the token scopes for more control over what the integration can do.

How is my access token stored?

Your token is stored in an encrypted form in our database. The database itself is stored on dedicated servers at the Hetzner Online provider, which ensures top-level physical security. You can learn more on the Hetznet website.

We take regular snapshots of the database and store them in a 256-bit encrypted Amazon S3 bucket for 30 days.

Did this answer your question?