多言語サイトでは、記事の本文に同じ添付ファイル (PDF、設定ファイル、スクリプトなど) が含まれることがよくあります。 ダウンロード リンクが言語バージョンごとに手動で管理されている場合、後でリンクの不一致やファイルの損失が簡単に発生する可能性があります。

この記事では、この問題を解決するために、直接再利用可能な Hugo ショート コード bundle-file を提供します。

ターゲット

同じ記事の多言語ファイルと添付ファイルを同じページ バンドル ディレクトリに配置します。次に例を示します。

1
2
3
4
5
6

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

これにより、リソースの再利用を最大限に高め、重複コピーを減らすことができます。 Hugo がそれを HTML に変換すると、コピーを繰り返すことなく、複数の言語が同じ添付ファイルをポイントできることが期待されます。

ショートコードの実装

ファイル:layouts/shortcodes/bundle-file.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{{- $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 の動作は単純です。

1. 現在のページのリソースからのファイルの検索を優先します。
2. 現在の言語が見つからない場合は、他の翻訳ページに移動して、同じ名前のファイルの検索を続けます。
3. 見つかった場合はダウンロードリンクが出力されます。見つからない場合は、見つからないファイル名を入力するよう求められます。

パラメータの説明

• name: 添付ファイル名、必須。
• text: リンク表示テキスト、オプション。送信されない場合は、デフォルトで name が表示されます。

使用例

1

Missing file: demo.pdf

text が渡されない場合:

1

Missing file: demo.pdf

公開前に確認してください

1. 添付ファイルは記事と同じページ バンドル内にあります。
2. name は実際のファイル名とまったく同じです (大文字と小文字を含む)。
3. リンクをクリックしてローカルでプレビューし、アクセスできることを確認します。

要約する

bundle-file は、多言語記事の添付リンク管理を「パスの手動管理」から「ルールに従った自動検索」に変更します。 ナレッジ ベースや技術ブログの長期メンテナンスの場合、これによりリンク エラー率が大幅に削減され、リリース前のトラブルシューティングのコストが削減されます。