A GitHub Action to automatically translate documentation using machine translation services.
- Automatically translates documentation into multiple languages
- Creates a pull request with translated content
- Fully customizable translation arguments
- Customizable pull request details
- Supports scheduled or manual triggering
Create a workflow file (e.g., .github/workflows/translate-docs.yml
) in your repository:
name: Translate Documentation
on:
schedule:
- cron: '0 20 * * *' # Daily at 20:00 UTC (DeepSeek API off-peak pricing window 16:30-00:30 UTC)
workflow_dispatch: # Allow manual triggering
inputs:
custom_arguments:
description: 'Custom arguments to pass to the translation package command'
required: false
type: string
permissions:
contents: write
pull-requests: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- name: Translate docs
uses: TanStack-dev/translate-docs-action@v1
with:
api_key: ${{ secrets.OPENAI_API_KEY }}
custom_arguments: ${{ github.event.inputs.custom_arguments }}
name: Translate Documentation
on:
schedule:
- cron: '0 20 * * *' # Daily at 20:00 UTC
workflow_dispatch: # Allow manual triggering
inputs:
custom_arguments:
description: 'Custom arguments to pass to the translation package command'
required: false
type: string
permissions:
contents: write
pull-requests: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- name: Translate docs
uses: TanStack-dev/translate-docs-action@v1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
api_key: ${{ secrets.OPENAI_API_KEY }}
custom_arguments: ${{ github.event.inputs.custom_arguments }}
translation_package: '@your-org/your-translation-package'
base_branch: 'main'
pr_branch: 'docs/translations-update'
pr_title: 'Update documentation translations'
commit_message: 'chore: update translations for documentation'
pr_body: |
This PR updates the documentation translations automatically.
Generated by the translate workflow.
Name | Description | Required | Default |
---|---|---|---|
custom_arguments |
Custom arguments to pass to the translation package command | No | '' |
github_token |
GitHub token for creating PRs | No | ${{ github.token }} |
api_key |
API key for translation service (e.g., OPENAI_API_KEY) | Yes | N/A |
translation_package |
NPM package to use for translation | No | '@tanstack-dev/translate-docs' |
base_branch |
Base branch to create PR against | No | 'main' |
pr_branch |
Branch name for the PR | No | 'docs/update-translations' |
pr_title |
Title for the PR | No | 'Update translations' |
pr_body |
Body text for the PR | No | Default message |
commit_message |
Commit message for the translation changes | No | 'docs: update documentation translations' |
add_paths |
A comma or newline-separated list of file paths to commit. Paths should follow git's pathspec syntax. | No | 'docs/**' |
enable_formatting |
Whether to run code formatting before creating the PR | No | 'true' |
format_command |
The command to run for formatting code | No | 'pnpm prettier:write' |
This is often due to .gitignore
patterns that exclude build folders with language codes like es
(Spanish). If you have a line like es
in your .gitignore
, it will ignore all folders named es
, including your translated documentation.
To fix this issue, you should exclude your documentation folders from being ignored by using the negation pattern:
# build files
es
# we don't need to ignore the docs folder
!docs/es
This ensures that build output directories are ignored, but your Spanish documentation in the docs/es
directory will be included in your git repository and PRs.
For the best cost efficiency, we recommend running the translation job on a schedule during API off-peak pricing windows. For example, DeepSeek API has an off-peak pricing window from 16:30-00:30 UTC.
Yes, the workflow_dispatch trigger allows you to manually run the action for a specific language by providing the language code as an input.
MIT