GitHub App

What is a 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 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
Checks: Run GitHub checks on pull requests for your translations
Hardcoded strings detection: Get notified about hardcoded strings in your codebase
Triggers: Configure when uploads and auto-translations should happen
Tags: Organize translations using tags for better project management

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 a configuration file (simplelocalize-github.yml) in the root of your repository

Configuration

The basic configuration uploads source translations from GitHub to SimpleLocalize and creates a pull request with translated files.

# Upload English translations from GitHub to SimpleLocalize on every push
upload:
  files:
    - path: "src/locales/source_english.json"
      format: "single-language-json"
      language-key: "en"
      options:
        - UPDATE_TRANSLATIONS

# Download translations from SimpleLocalize to GitHub
download:
  files:
    - path: "src/locales/{lang}.json"
      format: "single-language-json"

# Create a pull request with translation updates
pull-request:
  title: "Update translations"

This configuration:

Uploads English translations from src/locales/source_english.json on every push
Downloads all language translations to src/locales/{lang}.json in the simplelocalize-translations branch
Creates a pull request with translation updates

Complete configuration with all available options.

# 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:
        - "UPDATE_TRANSLATIONS"
        - "TRIM_LEADING_AND_TRAILING_WHITESPACES"
        - "ACTIVATE_PRESENT_KEYS"
        - "DEPRECATE_NOT_PRESENT_KEYS"
    - path: "api/locales/en.yml"
      format: "yaml"
      language-key: "en"
      tags:
        - "backend"

# 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"

# Customize commits for translation updates
commit:
  title: "Update translations ({languageCount} languages: {languageKeys})"

# 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"
      options:
        - "WRITE_NESTED"
        - "EXCLUDE_DEPRECATED_KEYS"
      tags:
        - "frontend"
      language-keys:
        - "pl"
        - "es"
        - "fr"
        - "de"
    - path: "api/locales/{lang}.yml"
      format: "yaml"
      tags:
        - "backend"

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

# GitHub checks configuration (beta feature)
checks:
  coverage: # Missing translations
    filter:
      language-keys:
        - "en"
        - "pl"
  acceptance: # Unreviewed translations
    filter:
      language-keys:
        - "en"
  quality: # QA issues
    filter:
      language-keys:
        - "en"
        - "pl"
      min-severity: "HIGH" # or MEDIUM, or LOW

Optional features

Add these sections to the configuration when you need them:

Upload triggers - upload only on push or pull request to selected branches
Language-specific paths - set exact file paths for languages that don't follow the path pattern
Pull request - description, labels, assignees and branches of the pull request with translation updates
Commit message - custom title of commits with translation updates
Auto-translate - translate new texts automatically after upload
GitHub Checks - check missing and unreviewed translations, QA issues and hardcoded strings in pull requests

Upload translations

Upload translation files from GitHub to SimpleLocalize.

upload:
  when:
    push: # Upload on every push
  files:
    - path: "src/locales/source_english.json"
      format: "single-language-json"
      language-key: "en"
      options:
        - UPDATE_TRANSLATIONS

Options

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	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
`files[].language-paths`	Exact file paths of languages that do not follow `path`, see language-specific paths	No

When pull-request.types is not specified then default types are used:

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

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

Download translation files from SimpleLocalize to the GitHub branch.

download:
  files:
    - path: "src/locales/{lang}/{ns}.json"
      format: "single-language-json"
      sort: "LEXICOGRAPHICAL"
      tags:
        - "frontend"
      language-keys:
        - "pl"
        - "fr"

Options

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
`files[].language-paths`	Exact file paths of languages that do not follow `path`, see language-specific paths	No

Path patterns and placeholders

For upload and download path patterns can contain placeholders for dynamic file handling.

{lang} - language key from "Languages" tab
{ns} - namespace (useful for multiple translation files)
{customer} - customer key, download only. Files are exported once for every customer in the project, with customer-specific translations

# download or upload:
  files:
    - path: "locales/{lang}.json" # locales/en.json, locales/es.json
    - path: "src/{ns}/messages_{lang}.json" # src/common/messages_en.json, src/auth/messages_es.json
    - path: "assets/i18n/{lang}/{ns}.json" # assets/i18n/en/common.json, assets/i18n/es/auth.json

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 (requires uploading the source file with the UPDATE_ORDER option, see translation keys order)

Language-specific paths

When a few languages are stored in a different place than the path pattern describes, list their exact paths in language-paths instead of repeating the whole file configuration for every language. The other options of the file configuration (format, options, tags, etc.) apply to all languages.

language-paths maps the language key from the "Languages" tab to the file path. For example, Android keeps the default translations in values/strings.xml, without a language suffix:

upload:
  files:
    - path: "app/src/main/res/values-{lang}/strings.xml"
      format: "android-strings"
      language-paths:
        en: "app/src/main/res/values/strings.xml"
        pt-BR: "app/src/main/res/values-pt-rBR/strings.xml"

download:
  files:
    - path: "app/src/main/res/values-{lang}/strings.xml"
      format: "android-strings"
      language-paths:
        en: "app/src/main/res/values/strings.xml"
        pt-BR: "app/src/main/res/values-pt-rBR/strings.xml"

With this configuration:

en is uploaded from and downloaded to app/src/main/res/values/strings.xml
pt-BR is uploaded from and downloaded to app/src/main/res/values-pt-rBR/strings.xml
other languages use the path pattern, e.g., de is uploaded from and downloaded to app/src/main/res/values-de/strings.xml

Paths in language-paths cannot contain the {lang} placeholder, and two languages cannot share the same path. They can contain {ns} and {customer} placeholders. On upload, a file matching the path pattern is skipped when its language has its own path in language-paths.

Pull request

Specifies what pull requests for updated translations should look like. Pull requests can be triggered manually using "Push translations to GitHub" from the SimpleLocalize interface, or automatically when "Automatic push" is enabled in your project settings.

When "Automatic push" is enabled, pull requests are created automatically after any changes are made to translations in the editor.

pull-request:
  title: "Update translations"
  body: |
    This PR contains updated translations from SimpleLocalize.
    Please review the changes before merging.
  labels:
    - "translations"

Options

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

Commit message

Customize the title of commits with translation updates pushed to the GitHub branch.

# Customize commits for translation updates
commit:
  title: "Update translations ({languageCount} languages: {languageKeys})"

Options

Option	Description	Required	Default
`title`	Commit title	No	"Update translations for en and pl"

The default title lists up to two updated languages, e.g., "Update translations for 3 languages" for more. The title can contain placeholders:

{languageCount} - number of updated languages
{languageKeys} - updated language keys, separated by commas

Auto-translate

Automatically translate your project. Auto-translate is triggered only when at least one file was imported during the upload step.

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

Options

Option	Description	Required
`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

When pull-request.types is not specified then default types are used:

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

GitHub Checks (beta)

This feature is currently in beta, and configuration namings may change in the future, but the basic functionality is stable and safe to use.

GitHub checks create individual check runs on pull requests for every configured rule from the checks section.

# ...rest of the configuration...

checks:
  coverage:
    filter:
      language-keys: ["en", "pl"]
  acceptance:
    filter:
      language-keys: ["en"]
  quality:
    filter:
      language-keys: ["en", "pl", "es"]
      min-severity: HIGH # or MEDIUM, or LOW
  hardcoded-strings:
    include:
      - "src/**/*.{js,jsx,ts,tsx}"
      - "server/**/*.{js,jsx,ts,tsx}"
    exclude:
      - "**/vendor/**"
      - "**/dist/**"
      - "**/build/**"

Check types:

coverage - fails if there are some missing translations in the editor
acceptance - fails if there are any not accepted translations in the editor
quality - fails if there are any issues in the editor
hardcoded-strings - fails if there are any hardcoded strings in commited files

Workflow examples

Here are some examples of how to use SimpleLocalize with GitHub App:

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"]

Android setup

Upload the default values/strings.xml file and translations from values-{lang} directories, and download them back to the same places:

upload:
  files:
    - path: "app/src/main/res/values-{lang}/strings.xml"
      format: "android-strings"
      options:
        - "UPDATE_TRANSLATIONS"
      language-paths:
        en: "app/src/main/res/values/strings.xml"

download:
  files:
    - path: "app/src/main/res/values-{lang}/strings.xml"
      format: "android-strings"
      language-paths:
        en: "app/src/main/res/values/strings.xml"

Add a language-paths entry for every language whose directory name differs from its language key in SimpleLocalize, e.g., pt-BR: "app/src/main/res/values-pt-rBR/strings.xml".

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:
  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:
  language-keys:
    - "es"
    - "fr"
  when:
    pull-request:
      types:
        - "opened"
      branches:
        - "main"

Troubleshooting

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
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.

Resources

Last updated: October 29, 2026