GitHub Integration

Babelize integrates directly with GitHub to read your source code and raise pull requests with translated files.

Connecting GitHub

One connection covers everything: picking repositories, reading code and opening pull requests.

1. Go to Projects → New Project
2. Click Connect GitHub
3. Install the Babelize GitHub App on your account or organization and select which repositories it can access
4. Back in Babelize, pick a repository from the list

Already installed the App (for example, from an earlier project)? Connect GitHub only asks you to authorize it, and your repositories show up straight away. Use + Another account in the repository list to add an organization.

You can change repository access anytime from GitHub Settings → Applications → Babelize, or with Add it on GitHub under the repository list.

How It Works

Permissions

• Repository contents — read and write: read to scan your code, write to create the translation branch and its commits (Babelize never pushes to your existing branches)
• Pull requests — read and write, to open and update translation PRs
• Metadata — read, for repository information

Events: push (to notice new commits) and pull request (to see when a translation PR is merged or closed).

Auto-localize

On the Growth and Studio plans, Babelize can translate every push for you. Turn it on when you create the project (Keep translating when I push), or later from the Auto-localize card on the project page.

Turning it on needs push access to the repository, from a GitHub account connected to Babelize. One project per repository branch can use it.

1. You push to the project's branch (for example main).
2. Babelize waits until you stop pushing for a few minutes (5 by default; set anything from 1 to 60), so a burst of commits becomes one run.
3. It checks the changed files for new text. Nothing new, nothing runs and no credits are used.
4. It runs a babel on the latest commit. Strings it has translated before come from the lockfile, so you only pay for new ones.
5. It opens a pull request from babelize/<branch>, or updates the one that's already open. There's only ever one. Once you merge it, the next change opens a new one.

Babelize ignores its own commits, pushes that only touch locale files, and the merge of its own pull request, so it never loops. If you push your own commits to the babelize/<branch> pull request, Babelize adds its changes on top and never overwrites yours. If you and <branch> both changed the same file since, merge <branch> into the pull request and Babelize carries on from there.

Credits. Runs are billed to the project owner: Babelize credits first, then your own API key if credits run short. Each project has a monthly limit for push-triggered runs (2,000 credits by default). When it's reached, or credits run out with no key to fall back to, auto-localize pauses and the owner gets a notification and an email. It restarts next month, when you raise the limit, or once credits are back. Manual babels are never blocked by this limit.

Syncing

When your source code changes, keep translations up to date:

1. Open your project in the dashboard
2. Click Sync to pull the latest changes
3. Run Babelize again to translate new or modified strings

Sync status indicators:

• Synced — up to date with GitHub
• Behind — new commits available
• Reconnect — GitHub access needs re-authorization

Troubleshooting

"GitHub Authentication Failed"

1. Go to your Profile settings
2. Check if GitHub is connected
3. Re-authorize via Connect GitHub

"Failed to raise PR"

• Verify the Babelize GitHub App is installed on the repository
• Check you have write access to the repository
• Try re-running from the project page

Repository Not Showing Up

• Click Add it on GitHub under the repository list and add the repo to the Babelize installation
• For an organization's repository, use + Another account to install Babelize there; if you aren't an owner, GitHub sends the owners a request
• Click Refresh in the list once you're done