urls

urls.RelLangURL

返回带语言前缀(如果有)的相对 URL。

签名
urls.RelLangURL INPUT
返回类型
string
别名
relLangURL

这一页解决什么问题

多语言站点里给 <a href>、样式、脚本、图片填地址时,既要跟随 baseURL,又不能丢掉当前语言的语言前缀。用 urls.RelURL 会漏掉前缀,读者一点就跳到默认语言版本;urls.RelLangURL 会把语言前缀补上。

什么时候用,什么时候别用

该用:

  • 多语言站点的站内资源与站内链接(href、src);
  • 单语言站点也可用它(没有语言前缀时结果与 urls.RelURL 一致)。

别用:

  • 需要完整地址(RSS、OG、结构化数据、邮件)→ 用 urls.AbsLangURL;
  • 明确不需要语言前缀(全站共用资源)→ 用 urls.RelURL;
  • 页面之间的链接 → 用 urls.RelRef 或 urls.Ref,它们会校验目标是否存在。

用法

单语言与多语言配置都可以使用该函数。返回的 URL 取决于:

  • 输入是否以斜杠(/)开头
  • 项目配置中的 baseURL
  • 语言前缀(如果有)

下文示例使用这份项目配置:

toml
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2

输入不以斜杠开头

如果输入不以斜杠开头,结果 URL 相对于项目配置里的 baseURL。

以 baseURL = https://example.org/ 渲染 en 站点时

go-html-template
{{ relLangURL "" }}                         → /en/
{{ relLangURL "articles" }}                 → /en/articles
{{ relLangURL "style.css" }}                → /en/style.css
{{ relLangURL "https://example.org" }}      → https://example.org
{{ relLangURL "https://example.org/" }}     → /en
{{ relLangURL "https://www.example.org" }}  → https://www.example.org
{{ relLangURL "https://www.example.org/" }} → https://www.example.org/

以 baseURL = https://example.org/docs/ 渲染 en 站点时

go-html-template
{{ relLangURL "" }}                           → /docs/en/
{{ relLangURL "articles" }}                   → /docs/en/articles
{{ relLangURL "style.css" }}                  → /docs/en/style.css
{{ relLangURL "https://example.org" }}        → https://example.org
{{ relLangURL "https://example.org/" }}       → https://example.org/
{{ relLangURL "https://example.org/docs" }}   → https://example.org/docs
{{ relLangURL "https://example.org/docs/" }}  → /docs/en
{{ relLangURL "https://www.example.org" }}    → https://www.example.org
{{ relLangURL "https://www.example.org/" }}   → https://www.example.org/

输入以斜杠开头

如果输入以斜杠开头,结果 URL 相对于项目配置里 baseURL 的协议加主机部分。

以 baseURL = https://example.org/ 渲染 en 站点时

go-html-template
{{ relLangURL "/" }}          → /en/
{{ relLangURL "/articles" }}  → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css

以 baseURL = https://example.org/docs/ 渲染 en 站点时

go-html-template
{{ relLangURL "/" }}          → /en/
{{ relLangURL "/articles" }}  → /en/articles
{{ relLangURL "/style.css" }} → /en/style.css

完整示例(实测)

layouts/_partials/nav.htmlgo-html-template
[{{ relLangURL "" }}]|[{{ relLangURL "articles" }}]|[{{ relLangURL "/articles" }}]

Hugo 0.167.0 实测输出(渲染 en 站点),baseURL = "https://example.org/" 时:

[/en/]|[/en/articles]|[/en/articles]

baseURL = "https://example.org/docs/" 时:

[/docs/en/]|[/docs/en/articles]|[/en/articles]

你应当看到什么:前两项带上了 /docs/en/,第三项只有 /en/——前导斜杠让子路径 /docs/ 被丢掉。另外上游表格里那条 relLangURL "https://example.org/"(baseURL 为根时)得 /en,看起来不像地址,正是上游提示「很少是你想要的」的原因。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,Windows;多语言配置 defaultContentLanguage='en'、defaultContentLanguageInSubdir=true,语言 en、es;渲染 en 站点。

输入 结果 是否报错
"" /en/(baseURL 带子路径时为 /docs/en/) 否
"articles" /en/articles(/docs/en/articles) 否
"/articles"(前导斜杠) /en/articles——相对「协议 + 主机」,丢掉 /docs/ 否
"https://example.org" https://example.org 原样返回 否
"https://example.org/" 根部署得 /en;子路径部署得 https://example.org/ 否
"https://www.example.org"(别的子域) 原样返回 否
返回类型 string,永远不是 nil 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 子路径部署后样式、图片 404 输入带前导斜杠,语言前缀与子路径的组合被破坏(实测丢 /docs/) 省略前导斜杠
没报错但结果不对 切换语言后站内链接没变 用了 urls.RelURL,没有语言前缀 改用本函数
没报错但结果不对 站内链接变成完整域名 输入本身是完整地址,或与 baseURL 主机路径一致时被折叠 只传站内路径

更多排查入口见故障排查。