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.

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
• Much more to come soon!

Getting Started

Install the GitHub App

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

Create Configuration File

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

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
• Creates pull requests when translations are updated in SimpleLocalize

Complete Configuration Example

# 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"
      tags:
        - "frontend"
      language-keys:
        - "en"
        - "es"
        - "fr"
        - "de"
    - path: "api/locales/{lang}.yml"
      format: "yaml"
      tags:
        - "backend"
      exclude-empty: true

Configuration Options

Pull Request Section

Upload Section

Download Section

Path Patterns

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
• properties - Java properties files
• csv - Comma-separated values
• excel - Excel spreadsheets
• And many more...

View all supported formats

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/**/*.json"
      format: "single-language-json"
      language-key: "en"
      namespace-key: "{fileName}"

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

Best Practices

1. Use Descriptive Tags

Organize your translations with meaningful tags:

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

2. Configure Branch Restrictions

Only trigger uploads from stable branches:

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

3. Customize Pull Requests

Make PR reviews easier with good descriptions:

pull-request:
  title: "🌐 Translations update for v{version}"
  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"

4. 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
      exclude-empty: true

Troubleshooting

Common Issues

Q: The GitHub App is not creating pull requests

• Ensure the app has write permissions to your repository
• Check that your simplelocalize.yml file is valid YAML
• Verify that your download configuration includes the correct file paths

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: Translation files are not found

• Double-check file paths in your configuration
• Ensure placeholders ({lang}, {ns}) are used correctly
• Verify that the files exist in your repository

Getting Help

If you encounter issues:

1. Validate your YAML in the your project settings in SimpleLocalize (Loaded configuration)
2. Contact support at contact@simplelocalize.io

Resources

• File Formats Documentation
• Sample GitHub Project
• GitHub App Installation