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.