GitHub App

What is GitHub App?

SimpleLocalize GitHub App is a powerful integration that connects your GitHub repository with SimpleLocalize, giving you option to automate the translation process in a more developer-friendly way. It allows you to replace the current SimpleLocalize CLI workflow for the most common cases and extend it with features that will come in the future.

Install SimpleLocalize GitHub App for your project

Example Pull Request from SimpleLocalize bot in GitHub

Features

Automatic upload: Upload source translations from your repository to SimpleLocalize on every push or pull request
Automatic download: Download updated translations and create pull requests for review
Auto-translate: Automatically translate newly uploaded content using auto-translation
Triggers: Configure when uploads and auto-translations should happen (specific branches, event types)
Tags: Organize translations using tags for better project management
Pull requests: Configure pull request titles, descriptions, and labels
Reports: Get reports on translation updates on pull requests
Much more to come soon!

GitHub App vs CLI

GitHub App covers the most common workflows, and can do basically the same thing, giving you some more benefits like reports. SimpleLocalize CLI is better where you need a more sophisticated workflow that is not yet covered by GitHub App.

GitHub App makes it much easier to transfer and scale the workflow than the CLI, as it requires just a simple configuration file (simplelocalize-github.yml) in your repository and connecting the repository to your SimpleLocalize project.

Getting started

Install the GitHub App

Navigate to the Project Settings in SimpleLocalize
Click on "GitHub App" in the left sidebar
Follow the installation link to add the SimpleLocalize GitHub App to your GitHub account

Create configuration

Create a simplelocalize-github.yml file in the root of your repository. This file defines how the GitHub App should handle your translations.

Configuration reference

Minimal configuration

Here's the simplest configuration to get started with uploading and downloading translations:

upload:
  when:
    push:
  files:
    - path: "src/locales/en.json"
      format: "single-language-json"
      language-key: "en"
      options:
        - REPLACE_TRANSLATION_IF_FOUND # Updates translations if they already exist

download:
  files:
    - path: "src/locales/{lang}.json"
      format: "single-language-json"
auto-translate:
  when:
    push:
  language-keys:
    - "es"
    - "fr"

This configuration:

Uploads English translations from src/locales/en.json on every push
Downloads all language translations to src/locales/{lang}.json
Auto-translates Spanish and French texts on every push

You can skip upload, download, auto-translate section if you don't want to use that feature.

Complete configuration

# Pull request configuration for translation updates
pull-request:
  title: "🌐 Update translations"
  body: |
    This PR contains updated translations from SimpleLocalize.

    Please review the changes before merging.
  base-branch: "main"
  head-branch: "simplelocalize/translations"
  assignees:
    - "john-doe"
  labels:
    - "translations"
    - "i18n"

# Upload from GitHub to SimpleLocalize
upload:
  when:
    push:
      branches:
        - "main"
        - "develop"
        - "feature/*"
    pull-request:
      types:
        - "opened"
        - "synchronize"
      branches:
        - "main"
        - "feature/*"
  files:
    - path: "src/locales/en/{ns}.json"
      format: "single-language-json"
      language-key: "en"
      tags:
        - "frontend"
      options:
        - REPLACE_TRANSLATION_IF_FOUND
        - TRIM_LEADING_AND_TRAILING_WHITESPACES
    - path: "api/locales/en.yml"
      format: "yaml"
      language-key: "en"
      tags:
        - "backend"

# Download from SimpleLocalize to GitHub
download:
  pull-branch: "main"
  push-branch: "simplelocalize/translations"
  files:
    - path: "src/locales/{lang}/{ns}.json"
      format: "single-language-json"
      sort: "LEXICOGRAPHICAL"
      tags:
        - "frontend"
      language-keys:
        - "en"
        - "es"
        - "fr"
        - "de"
    - path: "api/locales/{lang}.yml"
      format: "yaml"
      tags:
        - "backend"

# Auto-translate configuration
auto-translate:
  enabled: true
  language-keys:
    - "es"
    - "fr"
    - "de"
  when:
    push:
      branches:
        - "main"
    pull-request:
      types:
        - "opened"
      branches:
        - "main"

Configuration options

Pull request

Creates pull requests with updated translations and summary when changes are detected in SimpleLocalize, or you use "Push translations to GitHub" from the SimpleLocalize interface. You can skip pull-request section if you don't want to create pull requests for translation updates.

Option	Description	Required	Default
`title`	PR title	No	"Update translations"
`body`	PR description	No	Auto-generated
`labels`	Labels to apply to PR	No	-
`assignees`	GitHub usernames to assign	No	-
`head-branch`	Branch with changes	No	`download.push-branch` value
`base-branch`	Branch to merge into	No	`download.pull-branch` value

Upload translations

Pull translation files from GitHub commits to SimpleLocalize. You can skip upload section if you don't want to upload translations from GitHub.

Upload can be triggered by two types of GitHub events: push (commits pushed to a branch) and pull request (pull request activity).

Option	Description	Required
`when.push.branches`	Branches that trigger uploads on push	No
`when.pull-request.branches`	Branches that trigger uploads on pull request	No
`when.pull-request.types`	Pull request activity types that trigger uploads	No
`files`	Array of file configurations	No
`files[].path`	Path to the source file	Yes
`files[].format`	Translation file format	Yes
`files[].language-key`	Source language code	Format dependent
`files[].options`	Upload options	No
`files[].tags`	Tags to apply to translations	No

Upload trigger behavior

Push events are triggered when commits are pushed to a branch. If when.push.branches is not set, uploads are triggered on pushes to any branch.

Pull request events are triggered when a pull request is opened, synchronized (new commits pushed to PR), or reopened. If when.pull-request.types is not set, the default activity types are: opened, synchronize, and reopened. If when.pull-request.branches is not set, uploads are triggered on pull requests targeting any branch.

Supported pull request activity types:

opened — a new pull request is created
synchronize — new commits are pushed to an existing pull request
reopened — a previously closed pull request is reopened
closed — a pull request is closed or merged
edited — pull request title or body is changed

Both when.push and when.pull-request triggers can be configured at the same time. The upload will be triggered by either event if it matches the configured filters.

Download translations

Push translation files from SimpleLocalize to GitHub branch. You can skip download section if you don't want to download translations to GitHub.

Option	Description	Required
`push-branch`	Into which branch push files	No
`pull-branch`	Base branch	No
`files`	Array of file configurations	No
`files[].path`	Output path pattern	Yes
`files[].format`	Translation file format	Yes
`files[].sort`	Sort translations	No
`files[].options`	Download options	No
`files[].language-keys`	Specific languages to download	No
`files[].tags`	Filter by tags	No

Auto-translate

Automatically translate newly uploaded content after a successful import. Auto-translate is triggered only when at least one file was imported during the upload step. You can skip auto-translate section if you don't want to use automatic translations.

Option	Description	Required
`enabled`	Enable or disable auto-translation	Yes
`language-keys`	Target languages for translation	No
`options`	Auto-translation options	No
`when.push.branches`	Branches that trigger auto-translate on push	No
`when.pull-request.branches`	Branches that trigger auto-translate on pull request	No
`when.pull-request.types`	Pull request activity types that trigger auto-translate	No

Auto-translate trigger behavior

For push events, if when.push.branches is not set, auto-translate runs on pushes to any branch (as long as files were imported).

For pull request events, the when.pull-request section must be explicitly configured for auto-translate to run. If when.pull-request is not present in the auto-translate configuration, auto-translate will not be triggered by pull request events — even if files were imported. When when.pull-request is configured but types is not set, the default activity types are: opened, synchronize, and reopened.

Auto-translate examples

Auto-translate on every push that imports files:

auto-translate:
  enabled: true
  language-keys:
    - "es"
    - "fr"

Auto-translate only on push to main and on pull requests:

auto-translate:
  enabled: true
  language-keys:
    - "es"
    - "fr"
  when:
    push:
      branches:
        - "main"
    pull-request:
      branches:
        - "main"

Auto-translate only when a pull request is opened (not on synchronize or reopened):

auto-translate:
  enabled: true
  language-keys:
    - "es"
  when:
    pull-request:
      types:
        - "opened"

Path patterns and placeholders

Use placeholders in file paths for dynamic file handling:

{lang} - language key from "Languages" tab
{ns} - namespace (useful for multiple translation files)

Examples

# Single file per language
path: "locales/{lang}.json"
# Result: locales/en.json, locales/es.json

# Namespaced translations
path: "src/{ns}/messages_{lang}.json"
# Result: src/common/messages_en.json, src/auth/messages_es.json

# Nested structure
path: "assets/i18n/{lang}/{ns}.json"
# Result: assets/i18n/en/common.json, assets/i18n/es/auth.json

Upload options

Configure how translations are processed during upload:

REPLACE_TRANSLATION_IF_FOUND - Replace existing translations
TRIM_LEADING_AND_TRAILING_WHITESPACES - Clean up whitespace

View all upload and download options

Supported file formats

The GitHub App supports all SimpleLocalize file formats, including but not limited to:

single-language-json - JSON with translations for one language
multi-language-json - JSON with multiple languages
yaml - YAML format
java-properties - Java properties files
xliff:1.2 - XLIFF 1.2 format
xliff:2.0 - XLIFF 2.0 format
localizable-xcstrings - macOS/iOS .xcstrings files
android-strings - Android XML strings
csv - CSV format with customizable columns
po - Gettext PO files

View all supported formats

Sort translations

You can change the default sort order using sort parameter with one of those values:

LEXICOGRAPHICAL - sort alphabetically using the lexicographical algorithm
NEWEST_KEYS_FIRST - sort by translation key creation date, newest first
NEWEST_KEYS_LAST - sort by translation key creation date, oldest first
NAMESPACES - sort by namespaces alphabetically
IMPORT_ORDER - sort by the import order

Workflow examples

Frontend + Backend setup

upload:
  when:
    push:
      branches: ["main", "develop"]
  files:
    # React frontend translations
    - path: "src/locales/en.json"
      format: "single-language-json"
      language-key: "en"
      tags: ["frontend"]

    # Node.js backend translations
    - path: "server/locales/en.yml"
      format: "yaml"
      language-key: "en"
      tags: ["backend"]

download:
  files:
    # Frontend translations
    - path: "src/locales/{lang}.json"
      format: "single-language-json"
      tags: ["frontend"]

    # Backend translations
    - path: "server/locales/{lang}.yml"
      format: "yaml"
      tags: ["backend"]

Multi-namespace setup

upload:
  files:
    - path: "locales/en/{ns}.json"
      format: "single-language-json"
      language-key: "en"

download:
  files:
    - path: "locales/{lang}/{ns}.json"
      format: "single-language-json"

Upload with auto-translate

Upload source translations on push and automatically translate them to target languages:

upload:
  when:
    push:
      branches:
        - "main"
  files:
    - path: "src/locales/en.json"
      format: "single-language-json"
      language-key: "en"

auto-translate:
  enabled: true
  language-keys:
    - "es"
    - "fr"
    - "de"
    - "pl"
  when:
    push:
      branches:
        - "main"

Pull request workflow with auto-translate

Upload translations from pull requests and auto-translate only when new PRs are opened:

upload:
  when:
    pull-request:
      types:
        - "opened"
        - "synchronize"
      branches:
        - "main"
  files:
    - path: "src/locales/en.json"
      format: "single-language-json"
      language-key: "en"

auto-translate:
  enabled: true
  language-keys:
    - "es"
    - "fr"
  when:
    pull-request:
      types:
        - "opened"
      branches:
        - "main"

Best practices

Use descriptive tags

Organize your translations with meaningful tags:

tags:
  - "frontend"
  - "user-interface"
  - "v2.0"

Configure branch restrictions

Only trigger uploads from stable branches:

upload:
  when:
    push:
      branches:
        - "main"
        - "release/*"
    pull-request:
      branches:
        - "main"
        - "release/*"

Customize pull requests

Make PR reviews easier with good descriptions:

pull-request:
  title: "🌐 Translations update"
  body: |
    ## Translation Updates

    This PR contains the latest translations from SimpleLocalize.

    ### What's included:
    - Updated translations for all supported languages
    - New translation keys added in recent commits

    Please review and merge when ready.
  labels:
    - "translations"
    - "auto-generated"

Handle large projects

For projects with many translation files, use specific language filters:

download:
  files:
    - path: "locales/{lang}.json"
      format: "single-language-json"
      language-keys:
        - "en"  # Source language
        - "es"  # Spanish
        - "fr"  # French

Troubleshooting

Common issues

Q: The GitHub App is not creating pull requests

Ensure the app has permissions to your repository
Check that your simplelocalize-github.yml file is valid YAML
Verify that your download configuration includes the correct file paths
Pull requests are created only when translations are updated in SimpleLocalize, it may take up to a few minutes after the change to see the pull request

Q: Uploads are not triggered

Check the when.push.branches and when.pull-request.branches configuration
For pull request events, make sure the activity type matches. By default, only opened, synchronize, and reopened are handled
Ensure the source files exist in the specified paths
Verify the file format matches your actual files
Make sure that your upload.files.path is correct and points to the existing files in your repository

Q: Auto-translate is not working

Auto-translate runs only when at least one file was imported during the upload step
For pull request events, the when.pull-request section must be explicitly configured in the auto-translate section
Check that enabled is set to true
Verify that language-keys contains the target languages you want to translate to
Check branch filters in auto-translate.when match the branch where the event occurred

Q: Commited files are not reflecting the content I expect Whenever you change the configuration file, please make sure that you delete the previous branch created by SimpleLocalize GitHub App to make sure that the new configuration is applied correctly. That guarantees that the files are generated from scratch according to the new configuration.

Q: All downloaded files has the same language!

Make sure that you have the correct language-keys defined in the download.files configuration for each file.