Skip to content

TanStack-dev/translate-docs-action

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

14 Commits
 
 
 
 
 
 

Repository files navigation

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:

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

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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published