Github Integration

You can integrate your GitHub account with Tolq to automatically translate content inside your application source code repository. Tolq monitors each new pull request to check for changes in source files and translates those changes automatically.

How It Works

Pull request created - Tolq detects new or modified translatable files
Translation initiated - Changes are automatically sent for translation
Additional commits - New commits to the pull request are also translated
Review translations - Review completed translations in your client translation overview
Auto-commit - When approved, Tolq commits translated files to the pull request

Integration Requirements

The integration has three requirements:

Webhook configuration in your GitHub project
Personal access token from a user account with repository permissions
tolq.ymlconfiguration file in your repository

Setup Process

1. GitHub User Account

We recommend creating a separate account for Tolq to access your repository. It is also possible to use any existing GitHub account that has the same access.

Personal Access Token Setup:

The GitHub user account will need to create a personal access token with repository rights:

Once your token is created, copy/paste it in our GitHub setup form.

2. Webhook Configuration

Tolq needs to know when new untranslated content has been pushed to your master branch or when a pull request is made in order to create new translation requests.

Setup Steps:

Access repository settings - Navigate to:
```
https://github.com/YOUR_COMPANY_NAME_IN_GITHUB/YOUR_REPOSITORY_NAME/settings/hooks/new
```
Replace in the link above:
- YOUR_COMPANY_NAME_IN_GITHUB with the name that you use in your GitHub account
- YOUR_REPOSITORY_NAME with the name of the repository that you want to do translations
Example: If we use the Backend of Tolq as example it will be:
```
https://github.com/Tolq/tolq/settings/hooks/new
```
Create new webhook with the following configuration:

Detailed Webhook Settings:

Payload URL will be https://api.tolq.com/github_callback
Select content type application/json
Please don't add anything secret
Select "Let me select individual events" and then in the list of checkboxes select the "Pull Requests", like in the picture below:
- Make the checkbox active select
Finally click "Add webhook"

3. Configuration File: `tolq.yml`

In order to specify where each of your translatable files are and where the translations should be delivered, a tolq.yml configuration file must be created in your repository root.

Configuration Structure:

All files needing translation must be set inside source_file for which you will need to specify its language in source_language and one or more languages in target_languages.

Example Configuration:

translations:
  - source_file: "locales/en.json"
    source_language: "en"
    target_languages: ["de", "fr", "es"]
    target_file: "locales/{language}.json"
    quality: "localization"
  
  - source_file: "i18n/messages.properties"
    source_language: "en" 
    target_languages: ["de", "fr"]
    target_file: "i18n/messages_{language}.properties"
    quality: "translation"

Configuration Fields:

source_file - Path to the file containing source content
source_language - ISO 639-1 language code for source content
target_languages - Array of target language codes for translation
target_file - Output path pattern (use {language} placeholder)
quality - Translation quality level (see options below)

Quality Levels

Within quality you must select any of our available quality codes. For detailed information about each quality level, see our Pricing and Quality documentation.

machine - AI-generated translations for high-volume, low-priority content
postediting - Machine translation refined by professional translators
translation - Professional translations suitable for product descriptions and general content
localization - Culturally adapted translations for marketing texts and websites
expert - Specialized translations for technical, legal, or medical content requiring domain expertise

Supported File Types

The GitHub integration supports various file formats commonly used for internationalization:

JSON Files (Most Common)

Application localization files
React/Angular/Vue internationalization files
Configuration files with translatable content
API response templates

Example JSON structure:

{
  "welcome_message": "Welcome to our platform",
  "navigation": {
    "home": "Home",
    "about": "About Us"
  }
}

Other Supported Formats

Properties files - Java internationalization files (.properties)
YAML files - Configuration and content files (.yml, .yaml)
XML files - Structured content files (.xml)
CSV files - Tabular translation data (.csv)

File Processing

File Handling

target_fileoverwritten - Completely replaced after every completed translation
Source file blueprint - New file generated using source_file as template
Placeholder replacement - {language} replaced with actual language code
Directory creation - Target directories created automatically if needed

JSON File Processing

For JSON files, Tolq will:

Preserve structure - Maintain the original JSON hierarchy
Translate values only - Keys remain in original language
Handle nested objects - Translate strings at any depth
Maintain formatting - Preserve indentation and structure

Workflow Integration

Development Process

Create feature branch with new translatable content
Open pull request - Tolq automatically detects changes
Translation processing - Content sent for translation based on quality settings
Review in Tolq - Monitor progress in your client translation overview
Automatic commit - Translated files committed to pull request when approved
Merge ready - Pull request includes both source changes and translations

Monitoring and Management

Translation status - Track progress in your Tolq account
Quality control - Review translations before auto-commit
Error handling - Notifications for configuration or processing issues
Cost tracking - Monitor translation costs per repository and project

Best Practices

Repository Organization

Dedicated translation directory - Keep translatable files in locales/, i18n/, or similar directories
Consistent naming - Use consistent patterns like {language}.json or messages_{language}.properties
JSON structure - Organize JSON keys logically for translator context
Version control - Include tolq.yml in version control for team access

Configuration Management

Quality selection - Choose appropriate quality levels for different content types
Language prioritization - Start with high-priority languages in target list
File organization - Group related translations in logical directory structures
Testing - Test configuration with small changes before large deployments

Troubleshooting

Common Issues

Webhook not triggering - Verify webhook URL and SSL settings
Token permissions - Ensure personal access token has repository write access
Configuration errors - Validate tolq.yml syntax and file paths
File conflicts - Check for naming conflicts in target file patterns
JSON syntax errors - Ensure source files are valid JSON before processing

Support

For GitHub integration support, contact us at [email protected] with:

Repository URL and configuration file
Error messages or unexpected behavior
Webhook delivery logs (if available)
Personal access token permissions (without sharing the actual token)