Hugo on KnightLi Blog

Uso de las habilidades de los agentes de IA para mantener un blog multilingüe de Hugo

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

Si mantiene un blog multilingüe de Hugo, probablemente se encuentre con un problema frecuente:

Después de terminar el contenido en chino, aún necesitarás las versiones sincronizadas en inglés y chino tradicional.
Todos los archivos de idioma deben mantener la misma estructura.
La portada debe traducirse respetando las reglas del formato Hugo.

sync-post-translations está diseñado exactamente para este escenario.

¿Qué problema resuelve esta habilidad?

El posicionamiento de sync-post-translations es sencillo:

Utilice index.zh-cn.md como archivo fuente
Genere o actualice index.en.md e index.zh-tw.md en el mismo directorio
Mantenga coherente la estructura de Markdown
Aplique reglas explícitas al principio (especialmente “fecha” y “slug”)

Ejemplos de frases desencadenantes:

“Sincronizar traducción al inglés y chino tradicional”
“Traducir esta publicación al inglés y chino tradicional”

Estructura del directorio de habilidades

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

Código central 1: SKILL.md

A continuación se muestra el archivo de reglas básicas de esta habilidad:

---
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. 章节内容完整，不省略示例、注意点与总结。

Código central 2: agentes/openai.yaml

Este archivo define cómo se presenta y solicita la habilidad en el lado del agente:

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 构建校验。"

Ejemplo de uso práctico

1) Activador del lenguaje natural

1
2

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

2) Resultado esperado

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

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

Por qué son importantes estas reglas

Mantener “slug” sin cambios conserva las URL estables y los vínculos de retroceso históricos.
Normalizar la “fecha” a RFC3339 con zona horaria evita la ambigüedad en el análisis de Hugo/tema.
Mantener la estructura de Markdown sin cambios evita problemas de representación de TOC, bloques de código y códigos cortos.
No traducir identificadores técnicos reduce significativamente las discrepancias entre archivos y comandos rotos.

Errores comunes y cómo evitarlos

Si title contiene : sin comillas, el análisis de YAML puede fallar.
Traducir --flags, URL o nombres de paquetes interrumpirá los ejemplos de comandos.
Si los niveles de encabezado difieren entre idiomas (por ejemplo, ## se convierte en ###), los anclajes pueden volverse inconsistentes.
Traducir solo el contenido del cuerpo, pero no el texto inicial, puede romper las páginas de la lista y los metadatos de SEO.

Práctica de Hugo Shortcode: paquete-archivo (mantenga archivos y archivos adjuntos multilingües en un paquete de una página)

Sun, 29 Mar 2026 00:00:00 +0000

En sitios multilingües, las publicaciones suelen compartir los mismos archivos adjuntos (por ejemplo, PDF, archivos de configuración o scripts). Si cada versión de idioma mantiene enlaces de descarga manualmente, la pérdida de enlaces y los archivos perdidos se vuelven comunes con el tiempo.

Este artículo presenta un código corto de Hugo reutilizable, “bundle-file”, para resolver este problema.

Objetivo

Mantenga los archivos de publicaciones y archivos adjuntos multilingües en el mismo directorio del paquete de páginas, por ejemplo:

content/post/2026/03/09/01/
  index.zh-cn.md
  index.zh-tw.md
  index.en.md
  demo.pdf
  script.sh

Esto maximiza la reutilización y evita copias duplicadas. Después de que Hugo cree páginas HTML, todas las versiones de idiomas deben apuntar al mismo archivo adjunto en lugar de archivos duplicados.

Implementación de código corto

Archivo: layouts/shortcodes/bundle-file.html

{{- $name := .Get "name" -}}
{{- $text := .Get "text" | default $name -}}

{{- $res := .Page.Resources.GetMatch $name -}}
{{- if not $res -}}
  {{- range .Page.AllTranslations -}}
    {{- if not $res -}}
      {{- $tmp := .Resources.GetMatch $name -}}
      {{- if $tmp }}{{ $res = $tmp }}{{ end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- if $res -}}
<a href="{{ $res.RelPermalink }}">{{ $text }}</a>
{{- else -}}
<span>Missing file: {{ $name }}</span>
{{- end -}}

bundle-file funciona con una estrategia simple:

Primero busque el archivo en los recursos de la página actual.
Si no lo encuentra, busque el mismo nombre de archivo en otras páginas traducidas.
Genere un enlace de descarga cuando lo encuentre o muestre un mensaje de archivo faltante cuando no lo encuentre.

Parámetros

name: nombre del archivo adjunto (obligatorio)
text: etiqueta del enlace (opcional); por defecto es nombre

Ejemplo de uso

`1`	`Missing file: demo.pdf`

Sin “texto”:

`1`	`Missing file: demo.pdf`

Lista de verificación previa a la publicación

Coloque archivos adjuntos y publicaciones en el mismo paquete de páginas.
Asegúrese de que “nombre” coincida exactamente con el nombre de archivo real (incluido el caso).
Haga clic en los enlaces en la vista previa local para confirmar la accesibilidad.

Resumen

bundle-file convierte el manejo de archivos adjuntos multilingües del mantenimiento manual de rutas a una búsqueda automática basada en reglas. Para bases de conocimientos y blogs técnicos de larga duración, esto reduce el riesgo de enlaces rotos y el tiempo de revisión previa al lanzamiento.