GitHub Action

Translate JSON, YAML, and Markdown files in CI/CD with Langbly Translate, the official Langbly GitHub Action. Version 1.2.0 is live in GitHub Marketplace under Localization and Utilities.

Versioning

Pin Langbly/translate@v1. The v1 major tag tracks the latest v1.x release and currently resolves to v1.2.0 (verified July 27, 2026 against the tag list). An immutable v1.2.0 tag will be added by a separate release decision; until then the v1 major tag is the supported pin.

Quick start

name: Translate

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: Langbly/translate@v1
        with:
          api-key: ${{ secrets.LANGBLY_API_KEY }}
          source-language: en
          target-languages: nl,de,fr,es
          files: locales/en.json
          output-pattern: 'locales/{lang}.json'

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'Update translations'

Inputs

Input	Required	Default	Description
api-key	Yes	-	Langbly API key stored as a GitHub secret
source-language	Yes	en	Source language code
target-languages	Yes	-	Comma-separated target language codes
files	Yes	-	Source file or glob
output-pattern	Yes	-	Output path containing {lang}
format	No	auto	json, yaml, markdown, or auto
create-pr	No	false	Commit translated files to a new branch and open a PR
dry-run	No	false	Show planned work without writing files

Outputs

Output	Description
files-translated	Number of files written
characters-used	Number of source characters sent to the API

YAML example

- uses: Langbly/translate@v1
  with:
    api-key: ${{ secrets.LANGBLY_API_KEY }}
    source-language: en
    target-languages: nl,de,fr
    files: config/locales/en.yml
    output-pattern: 'config/locales/{lang}.yml'

Create a pull request

The Action can commit the translated files to a new branch and create a pull request. Grant only the required repository permissions:

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: Langbly/translate@v1
        with:
          api-key: ${{ secrets.LANGBLY_API_KEY }}
          source-language: en
          target-languages: nl,de,fr
          files: locales/en.json
          output-pattern: 'locales/{lang}.json'
          create-pr: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Incremental translation

For JSON and YAML, existing translated keys are preserved and only missing keys are sent to Langbly. Common placeholders such as {name}, {{count}}, %s, %1$s, ${value}, and $t(key) are protected.

API key

1. Create a Langbly account and add payment details.
2. Create an API key in the Langbly dashboard.
3. In GitHub, open Settings → Secrets and variables → Actions.
4. Add a repository secret named LANGBLY_API_KEY.

There is no base fee. The first 500,000 input characters each month are included after payment activation; additional usage costs $5 per million input characters.

Workflow recipes

Three complete, copyable workflows for the most common setups. They also live in the action repository under examples/, validated by npm run validate:examples there. All three use only the documented inputs and outputs above and the LANGBLY_API_KEY repository secret.

1. Translate locale JSON files in CI

Translates locales/en.json on every push to main that changes it and commits the results back. No push loop: the paths: filter only matches the source file, and the commit-back writes locales/{lang}.json files. contents: write is the only permission needed.

name: Translate locale JSON

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'
  workflow_dispatch: {}

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: translate
        uses: Langbly/translate@v1
        with:
          api-key: ${{ secrets.LANGBLY_API_KEY }}
          source-language: en
          target-languages: nl,de,fr,es
          files: locales/en.json
          output-pattern: 'locales/{lang}.json'

      - name: Report usage
        run: |
          echo "Files translated: ${{ steps.translate.outputs.files-translated }}" >> "$GITHUB_STEP_SUMMARY"
          echo "Characters used: ${{ steps.translate.outputs.characters-used }}" >> "$GITHUB_STEP_SUMMARY"

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'chore(i18n): update translations'
          file_pattern: 'locales/*.json'

2. Translate Markdown documentation

Translates documentation body content while preserving frontmatter. Pull requests get a dry-run preview (no files written); pushes to main translate for real and commit. Set format: markdown explicitly, or let the action auto-detect from the extension.

name: Translate documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/en/**'
  pull_request:
    paths:
      - 'docs/en/**'

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: translate
        uses: Langbly/translate@v1
        with:
          api-key: ${{ secrets.LANGBLY_API_KEY }}
          source-language: en
          target-languages: nl,de
          files: 'docs/en/**/*.md'
          output-pattern: 'docs/{lang}/**/*.md'
          format: markdown
          dry-run: ${{ github.event_name == 'pull_request' }}

      - name: Report usage
        run: |
          echo "Files translated: ${{ steps.translate.outputs.files-translated }}" >> "$GITHUB_STEP_SUMMARY"
          echo "Characters used: ${{ steps.translate.outputs.characters-used }}" >> "$GITHUB_STEP_SUMMARY"

      - uses: stefanzweifel/git-auto-commit-action@v5
        if: github.event_name == 'push'
        with:
          commit_message: 'docs(i18n): update translated documentation'
          file_pattern: 'docs/**'

3. Update multiple languages via pull request

Instead of committing to main, the action commits the translated files to a new branch and opens a pull request for review (behavior added in v1.2.0). Grant exactly contents: write and pull-requests: write, nothing more.

name: Update translations via PR

on:
  push:
    branches: [main]
    paths:
      - 'locales/en.json'
  workflow_dispatch: {}

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: translate
        uses: Langbly/translate@v1
        with:
          api-key: ${{ secrets.LANGBLY_API_KEY }}
          source-language: en
          target-languages: nl,de,fr,es,ja
          files: locales/en.json
          output-pattern: 'locales/{lang}.json'
          create-pr: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Report usage
        run: |
          echo "Files translated: ${{ steps.translate.outputs.files-translated }}" >> "$GITHUB_STEP_SUMMARY"
          echo "Characters used: ${{ steps.translate.outputs.characters-used }}" >> "$GITHUB_STEP_SUMMARY"

Failure handling and limitations

• The action retries transient API errors (429/5xx) with exponential backoff. On persistent failure the job fails; with create-pr no branch or PR is created. Re-run after resolving the cause (quota, invalid key, API status).
• Runs are incremental: only new or changed keys are sent to the API, so retries and reruns do not re-bill completed work.
• API calls are batched (max 50 strings / 10,000 characters per batch) to respect rate limits.
• Translation is machine translation: review output for user-facing or legal content, and use the PR recipe when you want a human gate.

Onboarding path

1. Open the Marketplace listing and pick a recipe above.
2. Create a Langbly account and add payment details (the first 500,000 input characters each month are included; then $5 per million input characters, no base fee).
3. Create an API key in the dashboard and add it as the LANGBLY_API_KEY repository secret.
4. Merge the workflow and watch the run; check per-language output and characters-used in the step summary.
5. Monitor usage and costs in the Langbly dashboard.

Links

• GitHub Marketplace
• Source repository
• Langbly pricing