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.

Example Pull Request from SimpleLocalize bot in GitHub

Features

Automatic upload: Upload source translations from your repository to SimpleLocalize on every push
Automatic download: Download updated translations and create pull requests for review
Triggers: Configure when uploads should happen (specific branches, file patterns)
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!

Share feedback on GitHub App

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

upload:
  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"

This configuration:

Uploads English translations from src/locales/en.json on every push
Downloads all language translations to src/locales/{lang}.json
Opens pull requests when translations are updated in SimpleLocalize

Skip upload or download sections if you only want to use the other feature. For example, if you only want to upload translations, you can omit the download section.

Complete configuration

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

    Please review the changes before merging.
  labels:
    - "translations"
    - "i18n"

# Upload configuration
upload:
  when:
    push:
      branches:
        - "main"
        - "develop"
        - "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 configuration
download:
  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"

Configuration options

Pull request

Option	Description	Required	Default
`title`	PR title	No	"Update translations"
`body`	PR description	No	Auto-generated
`labels`	Labels to apply to PR	No	-

Upload translations

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

Download translations

Option	Description	Required
`files`	Array of file configurations	Yes
`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

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:

single-language-json - JSON with translations for one language
multi-language-json - JSON with multiple languages
yaml - YAML format
java-properties - Java properties files
csv - Comma-separated values
excel - Excel spreadsheets
and many more...

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"

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/*"

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.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 configuration
Ensure the source files exist in the specified paths
Verify the file format matches your actual files

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.