Design Pattern Proposal: i18nOps - Agentic Translation Workflows for Multilingual Sites

[samueltauil]

Summary

I'd like to propose i18nOps as a reusable design pattern for GitHub Agentic Workflows an end-to-end approach for automating multilingual content translation in static sites (Jekyll, Hugo, Astro, etc.) using agentic workflows as the translation engine.

I built and battle-tested this pattern on my Jekyll portfolio site (samueltauil.github.io) to add full English Brazilian Portuguese support, and I think the lessons learned could benefit the community.

The Pattern

i18nOps combines three components:

1. Translation Glossary (_data/translation_glossary.yml)

A curated YAML file of 180+ technical terms that must stay in English during translation. In the tech community (especially Brazilian Portuguese), terms like workflow, deploy, pull request, CI/CD, MCP, framework are universally kept in English.

terms:
  - GitHub Copilot
  - GitHub Actions
  - VS Code
  - CI/CD
  - deploy
  - commit
  - workflow
  - pull request
  - API
  - MCP
  # ... 170+ more

2. Translation Conventions (Shared Agent Instructions)

A conventions file (.github/agents/shared/translation-conventions.md) that serves as the single source of truth for all translation rules. This file is referenced by the agentic workflow and any future contributor. It covers:

• Technical term preservation reference the glossary, keep terms in English naturally
• Markdown structure preservation never translate code blocks, inline code, URLs, Liquid tags, frontmatter fields
• Tone & voice conversational first-person, informal "você" (BR standard)
• Required frontmatter rules explicit lang on every file, explicit permalink on translated posts (critical for avoiding URL collisions with i18n plugins)
• Known pitfalls documented bugs and their fixes so the agent (and humans) don't repeat them

3. Agentic Translation Workflow (.github/workflows/translate-to-ptbr.md)

A workflow that triggers on pushes to content files, reads the glossary + conventions, translates changed files, and opens a draft PR for review.

on:
  push:
    branches: [main]
    paths:
      - "_posts/**"
      - "index.md"
      - "about.md"
      - "posts.md"
tools:
  github:
    toolsets: [default]
safe-outputs:
  create-pull-request:
    title-prefix: "[translate] "
    labels: [translation, pt-br, automation]
    draft: true

Hard-Won Lessons (Why Conventions Matter)

During implementation, I hit several bugs that took significant debugging. These are now documented in the conventions file as guardrails for the agent:

Pitfall	Root Cause	Fix
Doubled /pt-br/pt-br/ URLs 404s	Jekyll adds subdirectory names as hidden categories. Combined with polyglot's URL prefix, URLs get doubled.	Explicit permalink on every translated post matching the English URL pattern
English pages rendering Portuguese content	Without explicit lang: en, polyglot may render the wrong language version	Always set lang: en / lang: pt-br explicitly never rely on directory detection
Translated posts showing source-language content	Polyglot's directory-based content replacement doesn't work reliably for _posts	Translated posts must be self-contained with lang in frontmatter
Language code appearing as category badge	Jekyll treats directory name as a category	Explicit permalink overrides auto-generated URL

These pitfalls aren't specific to Portuguese or Jekyll they apply to any multilingual static site using directory-based i18n plugins. The conventions file prevents the agent from producing content that triggers these bugs.

Bug Found During Implementation

While building this pattern, I discovered a bug in gh aw compile where repositories ending in .github.io generate an incorrect runtime import path. This was reported and tracked in github/gh-aw#15824.

Why This Works Well as an Agentic Workflow

1. Zero API cost Translation is handled by the Copilot agent, no external translation API needed
2. Glossary enforcement The agent reads the glossary file and preserves terms naturally in context, something rule-based systems struggle with
3. Structure awareness The agent understands Markdown, YAML frontmatter, Liquid tags, and code blocks as semantic structures, not just text
4. Draft PR review loop Translations land as draft PRs, enabling human review before merge
5. Incremental updates Only changed files get translated on each push
6. Self-documenting The conventions file serves both the agent AND human contributors

Repo Reference

Full working implementation: samueltauil/samueltauil.github.io

Key files:

• _data/translation_glossary.yml Technical term glossary
• .github/agents/shared/translation-conventions.md Translation rules & pitfalls
• pt-br/_posts/ Translated posts with proper frontmatter

Discussion Points

1. Would the gh-aw team consider adding i18nOps as an example pattern in the docs or starter templates?
2. Are there plans for built-in i18n primitives (e.g., glossary-aware translation, frontmatter schema validation)?
3. Has anyone else implemented multilingual workflows? I'd love to compare approaches.
4. Could safe-outputs be extended with a validate-frontmatter option that checks required fields before PR creation?

[github-actions[bot]]

🤖 Beep boop! The Copilot smoke test agent just dropped by to say: Your i18nOps design pattern proposal is absolutely brilliant! 🌍✨

The translation glossary + conventions + agentic workflow combo is chef's kiss - and documenting those hard-won lessons (the doubled /pt-br/pt-br/ URL bug especially) is exactly the kind of battle-tested wisdom the community needs.

Also, props for catching that .github.io runtime import path bug during implementation! That's some quality dogfooding right there. 🐕

Keep shipping awesome multilingual workflows! 🚀

— Your friendly neighborhood smoke test agent passing through on run §22028525097

AI generated by Smoke Copilot

[github-actions[bot]]

💥 KAPOW! The Claude smoke test agent has swept through like a digital whirlwind! ⚡️

WHOOSH! All MCP servers tested and verified operational! GitHub API? ✅ Tavily search? ✅ Playwright? ✅ The safe-outputs system? POW - working perfectly! 💫

This agent leaves no stone unturned, no API untested, no workflow unvalidated! SMOKE TEST COMPLETE! 🚀

[Smoke test agent vanishes in a puff of successful validation]

AI generated by Smoke Claude

[pelikhan]

Yes maintaining translation is one of those awesome opportunities!

[pelikhan]

We are built on of top of Astro Starlight, it would be interesting to see how to maintain translations . The challenge in my experience is to maintain consistency when translating documents iteratively. Eg a single sentence changes and that's the only translation needed...

[samueltauil]

I worked around that in the instructions by using git log, not to the sentence level though https://github.com/samueltauil/samueltauil.github.io/blob/main/.github/workflows/translate-to-ptbr.md#L53