Hugo 模板指南SITE.Languages 方法——按语言权重获取全站点语言集合【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo.Site.Languages是 Hugo 多语言站点模板中用于获取「全部语言对象集合」的方法返回结果按各语言的weight配置排序常用于渲染语言切换器、遍历所有语言版本的站点入口等场景。本文以 Languages.md 文档为骨架结合当前仓库源码深入讲解其签名、排序语义、语言配置参数以及从 v0.156.0 起该方法被弃用后的正确迁移路径改用hugo.Sites帮助读者写出兼容新版本 Hugo 的多语言模板。方法签名与返回值按 Languages.md 的 front matter 定义签名SITE.Languages无参数返回类型langs.Languages其语义为Returns a collection of language objects for all sites, ordered by language weight. 返回所有站点的语言对象集合按语言权重排序。也就是说在多语言站点[languages.xx]配置块中{{ .Site.Languages }}会得到当前 Hugo 站点所配置的全部语言对象而不是当前正在渲染的那一个语言。当前语言的获取应使用.Site.Language。返回集合的排序语义按语言权重文档明确指出返回集合「ordered by language weight」。权重来自每个语言配置中的weight参数相关定义见 langs/config.go 中的LanguageConfig.WeightThe language weight. When set to a non-zero value, this will be the main sort criteria for the language.权重排序的底层实现在 langs/config.go 的init方法中LanguagesInternal会维护一份Sorted列表默认语言defaultContentLanguage指定的语言排在最前其余语言按weight升序排列weight为 0 的语言按配置声明顺序参与排序而设置了非零weight的语言则以权重为主排序依据。一个典型的双语言配置键即语言代码weight控制顺序defaultContentLanguage en [languages.de] contentDir content/de label Deutsch locale de-DE weight 1 [languages.en] contentDir content/en label English locale en-US weight 2此时{{ .Site.Languages }}会先返回de再返回en因为de的权重更小更靠前。从源码结构看这一排序贯穿站点构建全程HugoSites初始化站点时按该排序依次构建、渲染各个语言的站点。语言对象上可用的方法与配置项SITE.Languages返回的元素类型是langs.Language定义于 langs/language.go它是一个sitesmatrix.DimensionInfo实现持有语言代码、语言配置及内部翻译/排序器。可在模板中使用的成员包括方法/字段类型说明Name即Lang别名string语言代码即配置中[languages.xx]的键如deLabelstring语言显示名对应配置的label如Deutschv0.158.0 起Localestring区域设置对应配置的locale如de-DE未设置时回退到语言代码v0.158.0 起Directionstring书写方向ltr或rtl对应配置的directionv0.158.0 起Titlestring该语言覆盖的站点标题来自LanguageConfig.TitleWeightint语言权重v0.158.0 起已弃用该方法的直接访问IsDefaultbool是否为默认语言v0.153.0 起Paramshmaps.Params该语言的 params与对应站点的.Site.Params一致其中Label/Locale/Direction/Name对应 langs/config.go 中LanguageConfig的Label、Locale、Direction字段旧的LanguageName、LanguageCode、LanguageDirection字段均已在 v0.158.0 弃用由新字段替代。Locale的取值回退逻辑实现在 langs/language.go优先Locale其次旧字段LanguageCode最后是语言代码Lang。核心实践用 SITE.Languages 渲染语言切换器利用SITE.Languages最常见的场景是生成语言切换导航结合.Language判断当前语言并高亮ul classlang-switcher {{ range .Site.Languages }} li a href{{ .Name | printf /%s/ | relLangURL }} {{ if eq .Name $.Site.Language.Name }}classcurrent{{ end }} {{ .Label }} /a /li {{ end }} /ul由于集合按weight排序切换器中的语言顺序始终与配置意图一致不会因为渲染顺序而乱序。更稳健的写法是配合对应语言的站点首页链接使用hugo.Sites遍历每个语言站点的.Home.RelPermalink见下文迁移说明。重要v0.156.0 起弃用请迁移到 hugo.SitesLanguages.md 明确标注了该方法的状态弃用版本v0.156.0deprecated 2026-02-18到期移除日期expiryDate2028-02-18源码层面的弃用实现在 hugolib/site.go// Deprecated: See https://discourse.gohugo.io/t/56732. func (s *Site) Languages() langs.Languages { s.h.printSiteLanguagesDeprecationInit.Do(func() { hugo.Deprecate(.Site.Languages, See https://discourse.gohugo.io/t/56732., v0.156.0) }) return s.h.Configs.Languages }即每次调用该方法都会触发一次弃用告警通过 common/hugo/hugo.go 的Deprecate机制按版本级别输出日志。该方法本身只是返回s.h.Configs.Languages——即构建时解码并排序好的全部语言集合未做额外过滤。推荐的迁移路径是使用 v0.156.0 新增的hugo.Sites全局函数。它返回所有维度语言 × 版本 × 角色的全部站点且每个站点对象仍带有.Language等方法。官方文档示例hugo/Sites.md使用如下配置defaultContentLanguage en defaultContentLanguageInSubdir true [languages.de] contentDir content/de label Deutsch locale de-DE title Projekt Dokumentation weight 1 [languages.en] contentDir content/en label English locale en-US title Project Documentation weight 2对应模板ul {{ range hugo.Sites }} lia href{{ .Home.RelPermalink }}{{ .Title }}/a/li {{ end }} /ul当项目同时使用多语言、多版本[versions.xx]时hugo.Sites会遍历出所有组合站点这是旧SITE.Languages无法覆盖的扩展场景。hugo.Sites的源码实现见 hugolib/hugo_sites.go 的hugoSitesSitesProvider.Sites()它通过allSitesInterface聚合全部站点。源码视角方法的代理与调用链模板中的.Site对象经由 resources/page/site.go 的siteWrapper转发到hugolib的真实站点实现func (s *siteWrapper) Languages() langs.Languages { return s.s.Languages() }而langs.Languages类型本身定义于 langs/language.go本质是[]*Language的可排序切片并附带两个辅助方法AsSet()转成语言代码集合用于判断某个语言是否存在和AsIndexSet()语言代码到索引的映射。这类辅助方法在 Hugo 内部的多语言合并、页面归属判断等逻辑中被使用例如 hugolib/pagesfromdata/pagesfromgotmpl.go 中的EnableAllLanguages等页面数据能力也建立在语言维度之上。小结SITE.Languages是 Hugo 模板 API 中获取「全部语言对象、按 weight 排序」的直接入口配合语言配置中的weight、label、locale等参数可快速构建多语言站点导航。需要特别注意的是该方法自v0.156.0起已被标记为弃用预计2028-02-18到期移除新建项目或维护中的主题应优先改用hugo.Sites以同时兼容多语言、多版本、多角色的站点矩阵场景并在构建日志中避免弃用告警。【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考