Using AI Agent Skills to Maintain a Hugo Multilingual Blog

Mon, 06 Apr 2026 10:00:00 +0800

If you maintain a Hugo multilingual blog, you probably run into a frequent pain point:

After finishing Chinese content, you still need synchronized English and Traditional Chinese versions
All language files must keep the same structure
Front matter must be translated while still following Hugo format rules

sync-post-translations is built for exactly this scenario.

What Problem This Skill Solves

The positioning of sync-post-translations is straightforward:

Use index.zh-cn.md as the source file
Generate or update index.en.md and index.zh-tw.md in the same directory
Keep Markdown structure consistent
Apply explicit front matter rules (especially date and slug)

Example trigger phrases:

“Sync translation to English and Traditional Chinese”
“Translate this post to English and Traditional Chinese”

Skill Directory Structure

.\sync-post-translations\
├─ SKILL.md
└─ agents\
   └─ openai.yaml

Core Code 1: SKILL.md

Below is the core rules file of this skill:

---
name: sync-post-translations
description: 将 Hugo 文章从简体中文源文件（`index.zh-cn.md`）同步翻译为英文（`index.en.md`）和繁体中文（`index.zh-tw.md`）。当用户提出“en 繁体”“同步翻译英文繁体”或要求同时生成/更新两种语言版本且需保持 front matter 与 Markdown 结构一致时使用。
---

# 同步文章翻译

使用此技能为同一篇文章生成或更新多语言版本。

## 工作流程

1. 在目标文章目录中定位源文件 `index.zh-cn.md`。
2. 读取完整 front matter 与正文内容。
3. 在同目录创建或更新 `index.en.md` 与 `index.zh-tw.md`。
4. 确保三语结构对齐后执行 Hugo 构建检查。

## 翻译规则

1. 严格保留 `slug` 原值。
2. `date` 统一规范为 Hugo 常用带时间格式（RFC3339），示例：`2026-04-05T10:00:00+08:00`。
3. 自然翻译以下 front matter 字段：`title`、`description`、`tags`、`categories`。
4. 保持 Markdown 结构不变：标题层级、列表形态、代码块、链接与命令行示例。
5. 技术标识符保持原样：文件名、CLI 参数、模型名、设备名、URL、包名等。
6. 若 YAML 的 `title` 含有 `:`，必须加引号，避免解析报错。
7. 在不改变语义前提下，使用目标语言自然标点与表达习惯（`en`、`zh-tw`）。

## 输出约定

1. 仅在源文章同目录写入目标文件。
2. 汇报变更的文件路径。
3. 条件允许时执行 `hugo --source . --destination public`，并反馈通过/失败；失败时给出关键报错行。

## 质量标准

1. 全文术语前后一致。
2. 避免机器直译感，优先可发布文风。
3. 章节内容完整，不省略示例、注意点与总结。

Core Code 2: agents/openai.yaml

This file defines how the skill is presented and prompted on the agent side:

interface:
  display_name: "同步文章翻译"
  short_description: "生成或更新 EN + ZH-TW 翻译稿"
  default_prompt: "使用该技能在同一 Hugo 文章目录中，从 `index.zh-cn.md` 生成或同步 `index.en.md` 与 `index.zh-tw.md`，保留 `date` 与 `slug`，保持 Markdown 结构一致，并执行 Hugo 构建校验。"

Practical Usage Example

1) Natural language trigger

1
2

请把 content/post/2026/04/06/index.zh-cn.md 同步翻译成英文和繁体，
要求 date 用 RFC3339，slug 不变，最后跑 hugo 校验。

2) Expected output

已更新：
- content/post/2026/04/06/index.en.md
- content/post/2026/04/06/index.zh-tw.md

构建校验：
- hugo --source . --destination public
- 结果：PASS

Why These Rules Matter

Keeping slug unchanged preserves stable URLs and historical backlinks.
Normalizing date to RFC3339 with timezone avoids Hugo/theme parsing ambiguity.
Keeping Markdown structure unchanged prevents TOC, code block, and shortcode rendering issues.
Not translating technical identifiers significantly reduces broken command/file mismatches.

Common Pitfalls and How to Avoid Them

If title contains : without quotes, YAML parsing can fail.
Translating --flags, URLs, or package names will break command examples.
If heading levels differ across languages (for example, ## becoming ###), anchors can become inconsistent.
Translating only body content but not front matter can break list pages and SEO metadata.

Translation on KnightLi Blog