How do I connect GitHub and sync translations?
GitHub sync connects your repository to Better i18n, enabling two-way synchronization of translation files. When you push code changes, new keys are automatically imported. When you publish translations, changes can be pushed back as commits or pull requests.
Setting up GitHub
Step 1: Install the GitHub App
- Go to your project → Integrations tab
- Click GitHub → Install
- You'll be redirected to GitHub to install the Better i18n GitHub App
- Choose which repositories to grant access to
- Click Install
Step 2: Connect a repository
After installation:
- Select the repository that contains your translation files
- Configure the file pattern — where your translation files live:
/locales/{locale}.json— flat structure/locales/{locale}/{namespace}.json— namespaced folders/src/i18n/{locale}.json— custom path
- Click Connect
Step 3: Initial import
Better i18n will scan your repository and import all existing translation keys. You'll see an "Initial Import" job in the Sync tab.
How sync works
Code → Dashboard (automatic)
When you push to your connected branch:
- GitHub sends a webhook to Better i18n
- The sync worker scans changed translation files
- New keys are imported, updated keys are reflected in the dashboard
- You see the sync activity in the Sync tab
Dashboard → Code (on publish)
When you click "Publish to GitHub":
- Better i18n generates updated JSON files
- Changes are pushed as a commit to your branch (or as a PR)
- Your CI/CD pipeline deploys as usual
File format detection
Better i18n auto-detects your translation file structure:
| Format | Example path | How keys are organized |
|---|---|---|
| Flat JSON | /locales/en.json |
All keys at root, dot-notation |
| Namespaced | /locales/en/common.json |
One file per namespace |
| Nested | /locales/en.json |
Top-level keys become namespaces |
Sync history
The Sync tab shows all sync operations with:
- Job ID — unique identifier
- Status — Completed, In Progress, Failed, Cancelled
- Event — Initial Import, Source Sync, Batch Publish, CDN Setup
- Author — who triggered the sync
- Files/Keys — how many files and keys were affected
Click any job to expand its activity timeline and see detailed logs.
Disconnecting
To disconnect GitHub, go to Integrations → GitHub → Manage → Disconnect. Your translations remain in the dashboard — only the sync connection is removed.
Next steps
Cet article vous a-t-il été utile ?