Use this app to exchange files with your GitHub repository.
As soon as the app is set up, you can pull the files by using the Lokalise web dashboard. There will also be 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.
1. Connect your repository
Navigate to Apps, open GitHub, click Install and then Connect. Previously you had to generate a special access token on GitHub but that's not the case anymore. While you can still use personal access tokens for existing integrations, new setups involve OAuth 2 flow. All you have to do after clicking the Connect button is to give Lokalise Apps the necessary access rights.
repo scope is required for GitHub app.
Please note that if you are trying to connect Lokalise to a GitHub organization (not to a personal account) you will probably need to perform some additional steps as explained in the Note on GitHub organization section.
After that you can enter the Repository name (prefixed with your organization name) and the Branch to pull from:
As you export files from Lokalise, you can trigger the GitHub app 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 menu.
After the files are pulled, you can find your translation data in the Editor:
3. Add more repositories
As we recommend keeping all platform files within the same project, you may want to set up other repositories that apply to the same project. Click Add another repo to add more repositories.
Note on GitHub organizations
If you are trying to connect Lokalise to a GitHub organization but experience errors on the first step (after logging in with GitHub and giving Lokalise all the necessary access rights), you'll need to perform some additional actions:
Find Lokalise Apps in the Authorized OAuth Apps list and click on this app:
Find your organization in the Organization access section and click Grant:
Open your organization settings under the following URL:
https://github.com/organizations/YOUR_ORGANIZATION_NAME/settings/oauth_application_policy(this page can be found under Organization settings > Integrations > Third-party access). Make sure that the Lokalise Apps is approved. If not, click on the pen icon and manually set the status to "approved":
After performing these steps you can return to the Setup section and try connecting your repository again.
Use the Pull now button on the app page. Clicking the button will add the pull to the system queue to be executed in the background.
If you need to adjust the options, click Pull options on the app page:
These options are similar to the ones presented on the Upload page.
When you are satisfied with the initial pull results, it is a good idea to set up a webhook in GitHub which automates pulling the changes to Lokalise as you push to GitHub.
In GitHub, navigate to your repository settings > Webhooks and copy/paste the Auto-pull URL provided in the Lokalise app configuration. You will need to provide the Auto-pull secret generated on the app page as well.
As the translations are being completed, via download page 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 recommend triggering pull requests only to the repos of the platform that match the file type you are exporting, i.e. if you are exporting a JSON format, Lokalise will only create pull requests in repositories with the Web platform.
To actually create a pull request on GitHub, you should press Build only (this way you won't download a translations 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 is what happens after you trigger a new PR:
A new branch is created from the last revision of the branch you chose in the app setup. The branch name would look like this:
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 may then review and merge a pull request on 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 the Hetzner Online provider, which ensures top-level physical security (read more here https://www.hetzner.com/pdf/en/Sicherheit_en.pdf).
We take regular snapshots of the database and store them in a 256-bit encrypted Amazon S3 bucket for 30 days.
This type of app allows you to exchange files with a self-hosted GitHub Enterprise. The only difference is that 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:
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 in the same way as ordinary GItHub app.