🌍 Continuous Translation

July 21, 2025 · View on GitHub

Automatically translate your markdown documentation using AI - powered by GitHub Actions and GitHub Models with built-in support for Astro Starlight!

✨ Features

🚀 Incremental Translation - Only translates changed content, saving time and API costs
🎯 Smart AST Parsing - Preserves markdown structure and formatting
🔄 Cache Management - Intelligent caching to avoid redundant translations
📚 Astro Starlight Ready - Built-in support for documentation sites
🌐 Multi-language Support - Translate to multiple languages simultaneously
🔍 Quality Validation - Automatic validation of translation quality
⚡ GitHub Actions Native - Seamless integration with your CI/CD pipeline
🤖 AI-Powered - Leverage GitHub Models for seamless high-quality translations

📚 Resources

📖 Documentation - Complete setup guide and API reference (translated by this action too - see translation dashboard)
✍️ Blog Post - Deep dive into the technology
🌐 Translations: English | Français | Español | Portuguese (Brazil) | العربية

🔧 How It Works

This action leverages GenAIScript to intelligently analyze and translate your markdown documents. Here's the magic behind the scenes:

📄 Parse - Convert markdown to AST (Abstract Syntax Tree)
🔍 Analyze - Identify content that needs translation vs. existing translations
🤖 Translate - Use AI to generate high-quality translations
✅ Validate - Ensure translation quality and inject into document
💾 Cache - Save translations for future incremental updates
📝 Commit - Automatically commit changes to your repository

⚙️ Configuration

📝 Basic Settings

Parameter	Description	Default
`lang`	Target language(s) for translation (ISO codes, comma-separated)	`fr`
`source`	Source language (ISO code)	`en`
`files`	Files to translate (semicolon-separated)	`README.md`
`instructions`	Custom translation instructions	-
`instructions_file`	Path to file with translation instructions	-
`glossary_file`	Path to file with glossary terms	-
`translations_dir`	Folder to store translations	`translations`
`filename_template`	Jinja template to generate the translated filepath	`{{dirname}}/{{basename}}.{{lang}}{{extname}}`

Limits

Parameter	Description	Default
`max_translation_tokens`	Maximum available tokens for translation LLM call (to avoid rate limits)	`8000`
`max_validation_tokens`	Maximum available tokens for validation LLM call (to avoid rate limits)	`2000`

🌟 Astro Starlight Integration

Parameter	Description	Required
`starlight_dir`	Root folder of Astro Starlight documentation	Only for Starlight
`starlight_base`	Base alias for Starlight documentation	Optional

🔧 Diagnostics & Debugging

Parameter	Description	Default
`debug`	Enable debug logging (learn more)	`false`

🤖 AI Provider Configuration

GitHub Models (Recommended)

Parameter	Description	Default
`github_token`	GitHub token with `models: read` permission (setup guide)	`${{ secrets.GITHUB_TOKEN }}`

OpenAI

Parameter	Description	Default
`openai_api_key`	OpenAI API key	`${{ secrets.OPENAI_API_KEY }}`
`openai_api_base`	OpenAI API base URL	`${{ env.OPENAI_API_BASE }}`

Azure OpenAI

Parameter	Description	Default
`azure_openai_api_endpoint`	Azure OpenAI endpoint	`${{ env.AZURE_OPENAI_API_ENDPOINT }}`
`azure_openai_api_key`	Azure OpenAI API key (not needed for Microsoft Entra ID)	`${{ secrets.AZURE_OPENAI_API_KEY }}`
`azure_openai_subscription_id`	Subscription ID for deployment listing (Entra ID only)	`${{ env.AZURE_OPENAI_SUBSCRIPTION_ID }}`
`azure_openai_api_version`	Azure OpenAI API version	`${{ env.AZURE_OPENAI_API_VERSION }}`
`azure_openai_api_credentials`	API credentials type	`${{ env.AZURE_OPENAI_API_CREDENTIALS }}`

Model Alias

Parameter	Description	Default
`model_alias`	A YAML-like string of `alias: modelid` pairs

See the Models documentation for more details.

📤 Outputs

Output	Description
`text`	The generated translation text output

🚀 Quick Start

Simple Setup

Add this step to your GitHub Actions workflow to translate your README to French and Spanish:

uses: pelikhan/action-continuous-translation@v0
with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  lang: fr,es

Complete Workflow Example

Save this file in your .github/workflows/ directory as continuous-translation.yml:

name: Continuous Translation
on:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - "README.md"
      - "docs/src/content/docs/**"
permissions:
  contents: write
  models: read
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  continuous_translation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v4
        with:
          path: .genaiscript/cache/**
          key: continuous-translation-${{ github.run_id }}
          restore-keys: |
            continuous-translation-
      - uses: pelikhan/action-continuous-translation@v0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          lang: fr,es
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          file_pattern: "**.md* translations/**"
          commit_message: "[cai] translated docs"
          commit_user_name: "genaiscript"

Made with ❤️ using GenAIScript