Bitbucket Integration
Learn how to integrate MovaBase with Bitbucket for automatic translation syncing via pull requests
Bitbucket Integration
MovaBase provides seamless Bitbucket integration that allows you to automatically sync translations between your project and your Bitbucket repository using pull requests. This guide walks you through setting up and using the Bitbucket integration.
Overview
NEEDS_MEDIA
The Bitbucket integration enables you to:
- Automatic Syncing: Import translations from your Bitbucket repository
- Pull Request Workflow: Create pull requests with updated translations
- OAuth Authentication: Secure, token-based authentication with automatic refresh
- Flexible Configuration: Choose branches, paths, and export formats
- Real-Time Progress: Stream sync progress updates
- Format Support: Export to JSON, PO, Android XML, and iOS Strings formats
The Bitbucket integration uses OAuth 2.0 for secure authentication. Your credentials are never stored directly, and tokens are automatically refreshed for continuous access.
Prerequisites
Before setting up the Bitbucket integration, ensure you have:
- Bitbucket Account: An active Bitbucket account with repository access
- Repository Access: Write permissions to the target repository
- MovaBase Project: A project configured with your languages and translations
- Branch Strategy: Understanding of your repository's branch workflow
You need write permissions to the Bitbucket repository to create branches and pull requests. Read-only access will not work for the integration.
Setting Up Bitbucket Integration
OAuth Authentication
Access Integration Settings
Navigate to the Bitbucket integration in your project:
- Go to your project
- Click on the "Settings" tab
- Scroll to the "Integrations" section
- Click "Connect Bitbucket"
Authorize MovaBase
Click the authorization button to connect to Bitbucket:
- You'll be redirected to Bitbucket's OAuth authorization page
- Review the requested permissions
- Click "Grant access" to authorize MovaBase
- You'll be redirected back to MovaBase with authorization confirmed
MovaBase requests permission to read your repositories and create pull requests. Your code will never be accessed without your explicit action.
Select Workspace
Choose the Bitbucket workspace containing your repository:
- All workspaces you have access to are listed
- Select the workspace containing your target repository
- Only repositories from the selected workspace will be available
Select Repository
Choose the specific repository to connect:
- Repositories are loaded from the selected workspace
- Select the repository containing your translation files
- Ensure you have write permissions to this repository
Configure Integration
Set up the connection parameters:
- Branch: Target branch (default: main)
- Base Path: Directory path for translation files
- Format: Export format for translations
- Review all settings before connecting
Complete Connection
Finalize the integration setup:
- Click "Connect Repository"
- Wait for the connection to be established
- Success message confirms integration is active
- Configuration is saved for future use
NEEDS_MEDIA
Configuration Options
Branch Configuration
Choose the branch where translations should be synced:
| Branch Option | Description | Best For |
|---|---|---|
| main | Primary development branch | Direct deployment workflow |
| develop | Development branch | Feature-based development |
| custom | Any branch you specify | Specific workflow needs |
Choose a branch that matches your deployment workflow. For continuous deployment, use the branch that triggers your build process.
Base Path Configuration
Specify the directory where translation files are stored:
Ensure the base path exists in your repository and matches your application's file structure. The integration will fail if the path is invalid.
Export Format Selection
Choose the format for exported translations:
| Format | Extension | Platform | Use Case |
|---|---|---|---|
| JSON | .json | Web applications | JavaScript frameworks, React, Vue, Next.js |
| PO | .po | Linux/Desktop | Gettext format, internationalization libraries |
| Android XML | .xml | Android apps | Android resource files |
| iOS Strings | .strings | iOS apps | iOS/macOS resource files |
The selected format determines how translations are structured when exported to your Bitbucket repository.
Syncing Translations
Manual Sync
Manually sync your translations to Bitbucket:
Initiate Sync
Start the sync process from the integration panel:
- Click the "Sync to Bitbucket" button
- The sync process begins immediately
- Progress updates are displayed in real-time
Monitor Progress
Watch the sync progress as it completes:
- Current Operation: Shows what's being processed
- Progress Counter: Displays current/total files or translations
- Status Messages: Real-time feedback on sync status
- Error Notifications: Immediate alerts for any issues
Large projects may take several minutes to sync. The streaming progress keeps you informed throughout the process.
Review Results
After sync completes, review the summary:
- Number of files imported
- Number of translations updated
- Any errors or warnings
- Confirmation of successful sync
NEEDS_MEDIA
Sync Progress Updates
The sync process provides detailed progress information:
Pull Request Workflow
Creating Pull Requests
After syncing translations, create a pull request to integrate changes:
Open Pull Request Form
Access the PR creation dialog:
- Click "Create Pull Request" after sync completes
- The PR form opens with pre-filled information
- Review and customize as needed
Configure Pull Request
Set up the pull request details:
- Title: Descriptive PR title (auto-generated)
- Description: Summary of translation changes
- Branch: Source branch created for translations
- Target: Destination branch configured in settings
Submit Pull Request
Create the pull request in Bitbucket:
- Click "Create Pull Request"
- PR is created in your Bitbucket repository
- You're redirected to Bitbucket to review the PR
- Review changes and merge when ready
The pull request includes all translation file changes, making it easy to review and approve updates.
NEEDS_MEDIA
Pull Request Best Practices
Follow these guidelines for effective pull requests:
Use clear, descriptive PR titles:
- Good: "Update translations for v2.0 release"
- Good: "Add German translations for auth module"
- Bad: "Update translations"
- Bad: "Updates"
Include version numbers or feature names in PR titles to make them more informative.
Provide context in PR descriptions:
- List languages added or updated
- Describe major translation changes
- Note any deprecated translations removed
- Mention related issues or features
- Include testing instructions
Well-documented PR descriptions help reviewers understand the scope and impact of translation changes.
Establish a review process:
- Assign reviewers for translation quality checks
- Review changes language by language
- Test application with new translations
- Check for context and formatting issues
- Merge only after approval
Always test translations in your application before merging the pull request to catch formatting or context issues.
Managing the Integration
Viewing Current Configuration
Check your current integration settings:
Disconnecting Integration
Remove the Bitbucket integration if needed:
Access Disconnect Option
Find the disconnect button in the integration panel
Confirm Disconnection
You'll be asked to confirm:
- Review the confirmation message
- Understand that OAuth tokens will be revoked
- Know that configuration will be deleted
Disconnecting is irreversible. You'll need to reauthorize and reconfigure if you want to use the integration again.
Complete Disconnection
After confirming:
- OAuth tokens are revoked
- Configuration is removed
- Access to Bitbucket is terminated
- Integration panel shows disconnected state
Troubleshooting
Common Issues
Error Messages
| Error Message | Meaning | Solution |
|---|---|---|
| "Failed to load repositories" | Cannot access repository list | Check workspace permissions and reauthorize |
| "Branch not found" | Specified branch doesn't exist | Verify branch name and spelling |
| "Path not found" | Base path doesn't exist in repository | Correct base path or create directory |
| "Permission denied" | Insufficient write permissions | Grant write permissions or use authorized account |
| "Token expired" | OAuth token is no longer valid | Reauthorize the integration |
| "Rate limit exceeded" | Too many API requests | Wait and retry later |
Best Practices
Integration Setup
- Test First: Set up integration with a test repository first
- Use Feature Branches: Avoid syncing directly to main/production
- Document Configuration: Keep record of your integration settings
- Regular Testing: Periodically test sync and PR workflow
- Monitor Access: Review who has repository access
Sync Workflow
- Small Batches: Sync frequently with smaller changes
- Review Before Sync: Verify translations in MovaBase first
- Use Descriptive PRs: Make pull requests informative
- Test After Merge: Verify application works with new translations
- Rollback Plan: Know how to revert if issues occur
Establish a regular sync cadence (e.g., weekly or bi-weekly) to keep translations up-to-date and catch issues early.
Team Collaboration
Security Considerations
- Token Management: OAuth tokens are automatically refreshed
- Access Control: Limit who can configure integration
- Regular Audits: Review integration access periodically
- Secure Repository: Ensure repository access is properly managed
- Backup Strategy: Keep backups of critical translations
Never share your OAuth tokens or integration credentials. Rotate access if a team member leaves the project.
Advanced Features
Automatic Token Refresh
MovaBase automatically refreshes expired OAuth tokens:
Multi-Repository Integration
For organizations with multiple repositories:
Webhook Integration (Future)
Coming soon: Webhook-based automatic sync:
- Automatically sync when translations change in MovaBase
- Real-time updates to Bitbucket repository
- Configurable triggers and conditions
- Reduced manual sync operations
Stay tuned for webhook integration updates that will enable continuous synchronization.
Next Steps
Now that you understand Bitbucket integration, you can:
- Manage API Keys: Set up programmatic access for automation
- Configure User Roles: Control team access and permissions
- Set Up Profile Settings: Customize your account preferences
- Explore Export Options: Download translations in various formats
Part 11 of 14 • Bitbucket Integration Complete
Next: API Keys and Access