GitHub Action für HTML

Scanne HTML-Ordner aus statischen Builds, bewahre Markup mit format: html und committe Übersetzungen oder öffne einen PR — unterstützt durch das offizielle polylingo npm SDK.

Diese Seite ist in Ihrer Sprache noch nicht verfügbar — Anzeige auf Englisch.

PolyLingo GitHub Action — translate HTML in CI

This guide covers translate-action-html (repository): scan HTML in your repo, call PolyLingo with format: html, and write translated copies under a subdir or suffix layout. Pair it with static generators (Jekyll, Hugo, Sphinx, Eleventy, VitePress HTML export, etc.) or any checked-in HTML tree.

For JSON i18n + Markdown docs automation, see the companion GitHub Action for i18n (UsePolyLingo/translate-action).

Why HTML format matters

PolyLingo translates text nodes inside HTML while preserving structure: tags, attributes, classes, inline scripts, and URLs stay unchanged. That makes CI-safe bulk translation possible without hand-fixing broken markup.

See also: API reference — POST /translate and format.

Quick start

  1. Create an API key on Pricing.
  2. Add POLYLINGO_API_KEY as a repository secret.
  3. Point source_dir at your built HTML (often _site, dist, or docs/_build/html).
name: Translate HTML

on:
  push:
    branches: [main]

permissions:
  contents: write

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

      - uses: UsePolyLingo/translate-action-html@v1
        with:
          api_key: ${{ secrets.POLYLINGO_API_KEY }}
          source_dir: _site
          source_locale: en
          locales: fr,de,es,ja
          delta: 'true'
          commit: 'true'

Outputs and layouts

Subdirectory (output_layout: subdir, default):

  • index.html → fr/index.html, de/index.html
  • about/index.html → fr/about/index.html, …

Suffix (output_layout: suffix):

  • index.html → index.fr.html, index.de.html

Use output_dir when translated HTML should live beside sources under a different root (defaults to source_dir).

Delta mode

When delta: true, the action maintains <source_dir>/.polylingo-html-baseline.json with SHA-256 hashes per source file. Only changed files are sent to the API — commit the baseline with your translations.

Large sites

Set use_jobs_api: true to use jobs.translate() (async queue + polling) instead of synchronous translate(), which helps with very large HTML payloads or slow runs. Tune jobs_timeout (seconds).

Pull requests instead of direct commits

permissions:
  contents: write
  pull-requests: write

- uses: UsePolyLingo/translate-action-html@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_dir: _site
    locales: fr,de
    open_pr: 'true'
    pr_base_branch: main

exclude: vendor/**,node_modules/**,_layouts/**,_includes/**

_layouts / _includes are template fragments on many Jekyll-style trees — exclude them from scans when they appear under source_dir.

Inputs & outputs

See the action README on GitHub for the full inputs/outputs table:

PolyLingo GitHub Action — HTML in CI übersetzen | PolyLingo