Replexica GitHub Action

Replexica's GitHub Action automates localization in your CI/CD pipeline. It runs the Replexica CLI to translate missing strings, then commits and pushes the changes or creates a pull request.

How It Works

1. Runs replexica i18n to find and translate missing strings
2. Commits changes to your repo
3. Either pushes the commit directly or creates a pull request

This happens automatically on every push or pull request, keeping your translations up-to-date without manual intervention.

Why Use It

The Replexica GitHub Action solves a common problem in software development: keeping translations in sync with your rapidly evolving codebase. Here's why it's useful:

1. Consistency: By running on every push, it ensures your translations are always in sync with your source code. This consistency is hard to maintain manually, especially in fast-moving projects.

2. CI/CD Integration: It fits seamlessly into your existing CI/CD pipeline. This integration means localization becomes a natural part of your development process, not an afterthought.

3. Version Control: All translation changes are committed and pushed, giving you a clear history of when and how translations were updated. This traceability is valuable for debugging and auditing.

Setup

To use the Replexica GitHub Action, add this to your workflow file:

- uses: replexica/replexica@main
  with:
    api-key: ${{ secrets.REPLEXICA_API_KEY }}

The api-key is required. Store it as a secret in your GitHub repository settings.

If you want to use the pull request feature, you need to set the GH_TOKEN environment variable:

- uses: replexica/replexica@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.REPLEXICA_API_KEY }}
    pull-request: true

TIP

Important: Your workflow or job must have the following permissions enabled:

permissions:
  contents: write
  pull-requests: write

These permissions are necessary for the action to commit changes and create pull requests.

Security Considerations for Forks

If you're working with external forks and need to maintain strict security, you can use a approach that only checks out the necessary i18n files. This method allows you to grant write permissions without exposing your entire codebase. Here's an example:

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find apps/web/public/static/locales/** -name "common.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: replexica/replexica@main
        with:
          api-key: ${{ secrets.REPLEXICA_API_KEY }}

This workflow:

1. Checks out your repository
2. Selectively checks out only the i18n files from the fork
3. Runs the Replexica action on these files

This approach allows you to safely run the action on pull requests from forks without compromising security.

How It Operates

Here's a breakdown of the action's process:

1. It runs npx replexica@latest i18n to process translations.
2. It stages all changes (git add .).
3. If there are staged changes, it either:
   • Commits them, pulls and rebases to avoid conflicts, and pushes the changes; or
   • Creates or updates a pull request with the changes.

This process ensures that translation updates are seamlessly integrated into your codebase. The action uses this approach because it allows for automatic conflict resolution (via rebase) and provides a clear audit trail of translation updates.

Customization

You can customize the behavior using the following input parameters:

• pull-request: Set to 'true' to create a pull request instead of pushing directly (default: 'false')
• pull-request-title: Customize the title of the pull request (default: 'feat: update translations')
• commit-message: Customize the commit message (default: 'feat: update translations')
• pull_request_assignees: List of PR assignees (comma separated)
• pull_request_labels: List of PR labels (comma separated)

Example:

- uses: replexica/replexica@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.REPLEXICA_API_KEY }}
    pull-request: true
    pull-request-title: 'feat: update translations'
    commit-message: 'feat: update translations'
    pull_request_assignees: 'user1,user2'
    pull_request_labels: 'i18n,automated'

Note: The GH_TOKEN environment variable is required when pull-request is set to 'true'.

These customization options exist because different teams have different workflows and preferences. For instance, some teams might prefer pull requests for better review processes, while others might want direct commits for faster updates.

Considerations

While the Replexica GitHub Action is powerful, keep these points in mind:

1. Branch Strategy: When not using pull requests, the action commits directly to the current branch. Ensure this aligns with your branching strategy. This direct commit approach is faster but might not suit teams with strict code review policies.

2. Pull Requests: When using the pull request feature, ensure you have set the GH_TOKEN environment variable and the necessary permissions. This is crucial because GitHub requires proper authentication for creating pull requests programmatically.

3. Permissions: Remember to set the correct permissions in your workflow or job as mentioned in the setup section. Without these, the action won't be able to make changes to your repository.

4. Fork Security: If you're working with external forks, consider using the selective checkout method described in the "Security Considerations for Forks" section to maintain security while still allowing the action to run.

By automating localization with the Replexica GitHub Action, you're treating translations as a first-class citizen in your development process. This approach leads to more consistent, up-to-date multilingual applications with minimal manual effort. It's particularly beneficial for teams working on rapidly evolving products where keeping translations in sync can be a significant challenge.