https://github.com/TanStack-dev/translate-docs-action
https://github.com/TanStack-dev/translate-docs-action
Last synced: 3 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/TanStack-dev/translate-docs-action
- Owner: TanStack-dev
- Created: 2025-04-25T17:23:10.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-05-06T22:37:41.000Z (about 2 months ago)
- Last Synced: 2025-05-06T23:28:22.981Z (about 2 months ago)
- Size: 16.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-continuous-ai - Translate Docs - Translate your documentation into multiple languages automatically (Categories / Continuous Documentation)
- awesome-continuous-ai - Translate Docs - Translate your documentation into multiple languages automatically (Categories / Continuous Documentation)
README
# Translate Documentation Action
A GitHub Action to automatically translate documentation using machine translation services.
## Features
- 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
## Usage
### Basic usage in your workflow
Create a workflow file (e.g., `.github/workflows/translate-docs.yml`) in your repository:
```yaml
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 }}
```
### Advanced Configuration
```yaml
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.
```
## Inputs
| 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' |
## Q&A
### Why are my translated Spanish docs not showing in the PR?
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.
### How often should I run the translation job?
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.
### Can I manually trigger a translation for a specific language?
Yes, the workflow_dispatch trigger allows you to manually run the action for a specific language by providing the language code as an input.
## License
MIT