Introduction

Use this integration to exchange files with your GitHub repository. 

As soon as the integration is set up, you can pull the files by using the Lokalise web dashboard. There will be also an incoming webhook set up, which you may use to automatically pull the files as they are pushed to GitHub by your developer team. 

Once the translations are done, you can trigger the creation of a pull request when exporting.


Setup

1. Connect your repository

Navigate to project settings > Integrations and click Connect under the GitHub badge. 

You will need to generate and copy/paste a personal access token from GitHub. The token must have repo scope enabled.


Next, you can choose the Repository and Branch to pull from.

You must specify the platform of the files stored in this repo. As you export files from Lokalise, you can trigger the GitHub integration to create pull requests to repositories with a platform related to the exported file format.

It is important to decide whether you would like the filenames to include a full path. It is not needed in most cases, as you can configure the directory structure prefix at the pull request creation (export) step. However, when you have similar files in different subfolders, e.g. admin/locale.json  and frontend/locale.json, you need to enable the Include path in the filenames option. Keep in mind, that if you already have files uploaded to the project, including a path in the filenames at this step would mean that you are uploading different files.

2. Select files to pull

Browse the selected repository and select the files you want to pull and import.

In most cases, at this step you would only need to select the base language files (the files that are being modified locally and then pushed to GitHub). After selecting a file, you must set the language of the file in the dropdown.

3. Add more repositories

As we recommend keeping all platform files within the same project, you may want to set up another repositories that apply to the same project. Click Add another repo to add more repositories.


Pulling files

Manual pull

Use the Pull now button at the integration page (in project settings > Integrations). Hitting the button will add the pull to the system queue to be executed in the background.

Auto-pull

When you are satisfied with the initial pull results, it is a good idea to set up a webhook at GitHub which automates pulling the changes to Lokalise as you push to GitHub. 

At GitHub, navigate to your repository settings > Webhooks and copy/paste the Auto-pull URL provided in the Lokalise integration config. You will need to provide the Auto-pull secret generated at the integration page as well.


Pull requests

As the translations are being completed, Lokalise can create the pull requests with the exported files, which you can then merge to a selected branch. 

In order to create a pull request, you need to perform a project export with the GitHub trigger enabled. It is a good idea to use the Preview button first, so you can see the resulting file/folder structure before triggering the creation of a pull request.

We would trigger pull requests only to the repos of the platform that match the file type you are exporting, i.e. if you are exporting JSON format, Lokalise will only create pull requests in repositories with the Web platform.

Here is what happens as you trigger it:

  1. A new branch is created from the last revision of the branch which you have chosen in the integration setup. The branch name would look like this: lokalise-2018-03-12_15-14-13 .
  2. A commit with all the 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 a pull request at GitHub.

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

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 located at Hetzner Online provider, which ensures top-level physical security (read more here https://www.hetzner.com/pdf/en/Sicherheit_en.pdf).

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

Did this answer your question?