Product
Services
Solutions
BlogDocs
Login
Try it
Docs
Getting started
IntroductionCreating Your First ProjectSetting Up Your TeamBasic Localization Workflow
File Formats
File Formats OverviewJSON Format GuideXML (Android) Format GuideiOS .strings Format GuideiOS .stringsdict Format Guide (iOS Plurals)PO/POT/MO (Gettext) Format GuideSRT Subtitles Format Guide
Import & Export
File Upload Settings ConfigurationUniversal PlaceholdersFile Download Settings ConfigurationWorking with Plural Forms
Integrations
GitHub Integration - Complete Setup GuideGitLab Integration - Complete Setup Guide
Team Management
Roles and Access RightsTeam ManagementTeam ChatComments - Translation DiscussionLogs and Change History
Translation & Localization
Plurals and Arrays in Translation EditorUniversal Placeholders in Translation Editor
FAQ
Frequently Asked Questions (FAQ)
Back

GitLab Integration - Complete Setup Guide

Ilya Donder

Localit.io provides powerful GitLab integration, allowing you to automate localization workflow and synchronize translations directly with your repository. Both GitLab.com and self-hosted GitLab installations are supported.

Supported GitLab versions

GitLab.com (Cloud)

  • Standard integration with public and private repositories

  • Full feature support

  • Automatic webhooks

GitLab Self-Hosted

  • GitLab Community Edition (CE) support

  • GitLab Enterprise Edition (EE) support

  • Integration with corporate installations

  • Configuration through custom domains

  • Compatibility with corporate security policies

203

Initial integration setup

Step 1: Access settings

  1. Open your project in Localit.io

  2. Go to the "Integrations" section

  3. Select GitLab from the list of available services

204

Step 2: Choose token type

GitLab offers two types of access tokens:

  • Personal Access Token — user token with access to all their projects

  • Project Access Token — token for specific project (recommended)

Creating Personal Access Token

Step 1: Navigate to GitLab settings

  1. Click "Show token" in the Localit.io interface

  2. GitLab User Settings page will open

  3. Go to "Personal access tokens" section

205

Step 2: Create new token

  1. Click "Add new token"

  2. Fill in basic token information

206

Step 3: Configure basic parameters

Token name: Localit.io Integration
Expiration date: Pick the latest possible date
Description: Integration with Localit.io for automated localization workflow

207

Step 4: Configure permissions (Scopes)

Required permissions:

api:

  • Purpose: Full access to GitLab API

  • Needed for: Reading and writing files, repository management

208

read_repository:

  • Purpose: Reading repository content

  • Needed for: Loading localization files

209

write_repository:

  • Purpose: Writing to repository

  • Needed for: Sending translations back to repository

211

read_api:

  • Purpose: Webhook access

  • Needed for: Automatic synchronization on changes

212

Step 5: Create and copy token

  1. Click "Create personal access token"

  2. Important: Copy the token immediately — it won't be shown again

  3. Save the token in a secure location

213

Creating Project Access Token (Recommended)

More secure method for specific projects

Project Access Token limits access to only one project, enhancing security.

Step 1: Navigate to project settings

  1. Open the required project in GitLab

  2. Go to Settings → Access Tokens

  3. Find "Project Access Tokens" section

214

Step 2: Create Project token

  1. Click "Add new token"

  2. Fill in token parameters

215

Step 3: Configure Project token

Token name: Localit.io Integration Expiration date: No expiration (recommended) Role: Maintainer (minimum) or Owner

Required permissions (Scopes):

api:

  • Full access to GitLab API

read_repository:

  • Reading repository content

write_repository:

  • Writing to repository

read_api:

  • Webhook access for automatic synchronization

216

Step 4: Create and save token

  1. Click "Create project access token"

  2. Immediately copy the created token

  3. Save the token in a secure location

217

Configuring connection parameters in Localit.io

Step 1: Enter token

  1. Return to Localit.io interface

  2. Paste the copied token into "Personal access token" field

  3. System automatically validates the token

218

Step 2: Select repository

  1. Choose target repository from dropdown list

  2. Search by name available for convenience

  3. Only accessible repositories are displayed

226

Step 3: Specify working branch

  1. Specify working branch (usually main, master, or develop)

  2. Search by branch name available

  3. System shows all available branches

227

Platform and file configuration

Step 1: Choose platform type

Select platform type according to your project:

  • Web (.json, .po, .pot, .mo)

  • Android (.xml)

  • iOS (.strings, .stringsdict)

  • Other (.srt, custom formats)

228

Step 2: Add files

  1. Click "Next" to proceed to file selection

  2. Click "Add file"

  3. Select needed files in repository file tree

229

Step 3: Configure languages

  1. Specify corresponding language for each file

  2. System automatically detects language by file path

  3. Correct automatic detection if needed

219

Step 4: Save configuration

  1. Review all settings

  2. Click "Save"

  3. Integration will be configured and ready to use

220

Initial localization setup

Important for new projects

If you haven't translated your project to other languages yet, follow this workflow:

Step 1: Create empty localization files

  1. Create empty localization files in your GitLab repository

  2. Follow folder structure for your platform:

For iOS:

en.lproj/Localizable.strings
es.lproj/Localizable.strings  
fr.lproj/Localizable.strings

For Android:

app/src/main/res/values/strings.xml
app/src/main/res/values-es/strings.xml
app/src/main/res/values-fr/strings.xml

For Web:

src/locales/en.json
src/locales/es.json
src/locales/fr.json

Step 2: Connect integration

  1. Set up GitLab integration as described above

  2. Connect created files to project

  3. Perform initial Pull to load structure

Step 3: Translate keys

  1. Translate necessary keys using translation editor

  2. Or order automatic translation through AI services

  3. Review translation quality

Step 4: Send to GitLab

  1. Perform Push to send translations to repository

  2. Verify files updated in GitLab

  3. Test localization in application

Pull requests (Import from GitLab)

Initiating Pull request

  1. Go to project "Integrations" section

  2. Find connected GitLab repository

  3. Click "Pull" button

221

  1. Within seconds project will be updated - all keys from GitLab will be loaded into your Localit.io project

Parameter configuration: Pull request parameters correspond to manual file upload parameters. Details in File Upload Guide.

Automatic synchronization with GitLab

Function: Project automatically updates when repository changes Requirements: Webhook permission when creating token Benefits: Continuous synchronization without manual intervention

225

Push requests (Export to GitLab)

Initiating Push request

  1. Go to project "Integrations" section

  2. Find connected GitLab repository

  3. Click "Push" button

222

  1. Within seconds repository will be updated - all translations from Localit.io will be sent to your GitLab repository

Parameter configuration: Push request parameters correspond to manual file download parameters. Details in File Download Guide.

Troubleshooting

Token issues

Token not working:

  1. Check token expiration date in GitLab Settings

  2. Ensure correct copying (no extra spaces)

  3. Verify token permissions

223

Insufficient permissions:

  1. Return to token settings in GitLab

  2. Add missing permissions (api, read_repository, write_repository, read_api)

  3. For Project Access Token ensure Maintainer or Owner role

Repository issues

Repository not displayed:

  1. Ensure token has repository access

  2. Check that repository is not archived

  3. For private repositories ensure appropriate permissions

Files not synchronizing:

  1. Check correct file path specification

  2. Ensure files exist in specified branch

  3. Verify file format matches expected

Webhook issues

Automatic synchronization not working:

  1. Check webhook settings in GitLab project

  2. Ensure token has read_api permission

  3. Verify webhooks not blocked by firewall

224

GitLab Self-hosted specific issues

Self-hosted connection problems:

  1. Ensure correct GitLab server URL

  2. Check server network accessibility

  3. Consult GitLab administrator about security settings

Corporate policy restrictions:

  1. Contact GitLab administrator

  2. Request necessary integration permissions

  3. Clarify allowed external applications list

Project Access Token issues

Project token not working:

  1. Ensure token role is Maintainer or Owner

  2. Check token created for correct project

  3. Verify all necessary scopes are present

Best practices

Token security

Recommendations:

  • Use Project Access Token instead of Personal Access Token

  • Set minimal necessary permissions

  • Regularly update tokens

  • Remove unused tokens

Token comparison:

Token Type

Access Scope

Security

Recommended

Personal Access Token

All user projects

Medium

For multiple projects

Project Access Token

One specific project

High

Yes

Workflow organization

Branch strategy:

  • Use separate branch for localization

  • Configure automatic merge to main branch

  • Regularly synchronize changes

Change monitoring:

  • Set up Pull/Push operation notifications

  • Regularly check synchronization status

  • Maintain change logs for audit

In this article