GitHub App available!

The SimpleLocalize GitHub App is now live! You can connect your GitHub repository directly to SimpleLocalize and automate the most common localization workflows without scripting or manual CLI runs.

What you get

• Automatic upload of source translations on push
• Automatic download + pull requests with updated translations
• Smart path patterns with {lang} and {ns} placeholders
• Configurable branches, PR title/body, and labels
• Tag-based filtering and format flexibility
• Reports on translation updates in pull requests

How it works

The GitHub App listens to events in your repository, such as pushes or pull requests. When a change is detected, it automatically uploads source translations to SimpleLocalize and downloads updated translations back to your repository, by creating a pull request with the changes like this:

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.

Quick start

1. Install the SimpleLocalize GitHub App from your Project Settings (GitHub section)
2. Add a simplelocalize.yml file to the root of your repo
3. Commit & push

When translations change in SimpleLocalize, the app prepares updated files and opens a pull request for review. You keep full control over merging.

Minimal config

upload:
  files:
    - path: "src/locales/en.json"
      format: "single-language-json"
      language-key: "en"
      options:
        - REPLACE_TRANSLATION_IF_FOUND

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

GitHub App configuration file shares similar syntax in some parts to the SimpleLocalize CLI configuration file, but they are not interchangeable.

Placeholders

Use placeholders:

• {lang} - language key
• {ns} - namespace (when you split translations across files)

Example:

path: "src/i18n/{lang}/{ns}.json"

Generates: src/i18n/en/common.json, src/i18n/pl/dashboard.json, etc.

Resources

• Documentation: GitHub App
• Documentation: File formats