Replexica GitHub Action

Overview

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

You will also need to enable Allow GitHub Actions to create and approve pull requests in your repository: Settings -> Actions -> General.

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.

Example

To run the action on every push to a branch that starts with feat/, you can use the following workflow. It will commit and pushupdated locale files to the branch as you push commits with new features. Save the following file as .github/workflows/i18n.yml:

name: Replexica i18n

on:
  push:
    branches:
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: replexica/replexica@main
        with:
          api-key: ${{ secrets.REPLEXICA_API_KEY }}

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 via @replexica')
• commit-message: Customize the commit message (default: 'feat: update translations via @replexica')

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"

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

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.