Deprecations in v0.158.0

tips & tricks
1

Background

In v0.158.0 we renamed some language-related template methods and their corresponding project configuration settings. Although there were several reasons for doing so, the primary reason was to eliminate API stutter.

API stutter refers to a redundant naming convention where a library or package name is repeated in its own exported types or functions, such as Language.LanguageDirection.

Deprecated template methods

The following table outlines the transition from stuttering methods to cleaner and more precise alternatives.

Deprecated method Replacement Reason
Page.Language.Lang Page.Language.Name Eliminate API stutter and create naming symmetry with the version and role APIs.
Site.Language.Lang Site.Language.Name Same as above.
Page.Language.LanguageCode Page.Language.Locale Eliminate API stutter and adopt the industry-standard “Locale” to more accurately define language and region combinations such as en-US.
Site.Language.LanguageCode Site.Language.Locale Same as above.
Page.Language.LanguageDirection Page.Language.Direction Eliminate API stutter.
Site.Language.LanguageDirection Site.Language.Direction Same as above.
Page.Language.LanguageName Page.Language.Label Eliminate API stutter.
Site.Language.LanguageName Site.Language.Label Same as above.
Page.Language.Weight N/A This method is redundant in templates as the collections returned by Page.AllTranslations, Page.Translations, and Page.Rotate are already sorted by weight with a fallback to lexicographical order.
Site.Language.Weight N/A Same as above.
Site.LanguageCode Site.Language.Locale This is a formal deprecation of an undocumented method.

Although the Weight template methods are deprecated, you should continue to define weight for each language in your project configuration. It remains the primary sorting criterion for the page collections returned by Page.AllTranslations, Page.Translations, and Page.Rotate.

Deprecated configuration settings

We made symmetrical changes to project configuration settings:

Deprecated setting Replacement
languageCode locale
languageName label
languageDirection direction

Monolingual project example

For a monolingual project, change the languageCode key to locale at the root of your project configuration:

baseURL = 'https://example.org/'
locale = 'en-US'
title = 'Project Documentation'

Multilingual project example

For a multilingual project, change the languageCode, languageName, and languageDirection keys to locale, label, and direction within each language table:

baseURL = 'https://example.org/'

defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true

[languages.de]
  direction = 'ltr'
  label = 'Deutsch'
  locale = 'de-DE'
  title = 'Projekt Dokumentation'
  weight = 1
[languages.en]
  direction = 'ltr'
  label = 'English'
  locale = 'en-US'
  title = 'Project Documentation'
  weight = 2

Identify deprecated usage

Run hugo build --logLevel info to identify usage of the deprecated methods above. In about 3 months, the info log deprecation messages will be elevated to warnings, and about 12 months after that, they will be elevated to errors. This is in accordance with our published deprecation process.

3 Likes