Relative Time Plus

A jinja macro to display the difference between two datetimes in a readable format

Why this macro

I hear you thinking, there is already a relative_time filter/function in Home Assistant. And of course this is true, but it only returns the text in English, and always only returns the biggest time fraction. So this macro supports multiple languages (currently Dutch and English) and has some additional options.

How to install

Home Assistant 2023.11 or higher is required to use this macro.

This custom template is compatible with HACS, which means that you can easily download and manage updates for it. Custom templates are supported in HACS 2.0 or when you enable experimental features in the HACS settings of versions prior to 2.0.

For a manual install you can copy the contents of relative_time_plus.jinja to a jinja file in your custom_templates folder. Run the homeassistant.reload_custom_templates service call to load the file.

Languages

Current supported languages:

Language	Language code	Provided by
Bulgarian	bg	Georgi Iliev
Czech	cs	supperka
Danish	da	C4-Dimitri
Dutch	nl	TheFes
English	en	TheFes
Finnish	fi	samhaa
French	fr	Pulpyyyy
German	de	fastlane086
Hebrew	he	Ofir Manor
Hungarian	hu	terba
Italian	it	SiriosDev
Norwegian (bokmål)	nb	bendikrb
Norwegian (nynorsk)	nn	bendikrb
Polish	pl	darylosu
Portuguese	pt	FragMenthor
Russian	ru	wrun
Spanish	es	cvc90
Swedish	sv	tde01065
Ukranian	uk	laktiv
Vietnamese	vi	cuongpl

How to use

The only required field is the datetime you want to show as relative time. It can be eiter in the past or future, and you can use a datetime object, a timestamp (integer or float) or anything which can be converted to a datetime object using as_datetime.

You can also directly use an entity_id as input. The macro will retreive the state of the sensor automatically, and will also check if it is a sensor with state_class: duration. If that is the case, it will treat the input as duration instead of as a timestamp. In case an input_datetime entity is used, and this input_datetime is set to time only, the macro will convert it to that time today.

Other optional fields are:

name	type	default	example	description
parts	integer	1	3	The number of time fractions which should be used
not_use	list or string	['millisecond']	['yr', 'minute']	Provide the time periods you don't want to use in the output, by default only milliseconds are excluded. You can provide a list or a comma separated string, so 'yr, month' and ['yr', 'month'] will both work. Possible values are year, month, week, day, hour, minute, second, millisecond or the abbreviated versions yr, mth, wk, day, hr, min, sec, ms.
always_show	list or string	[]	['yr', 'mth', 'day']	Provide the time periods you always want to show, even when they are zero. With the example the output could be "0 years, 0 months and 19 days". Use 'all' to always show all time parts. You can use not_use to exclude time parts from 'all'
time	boolean	true	false	Set to false to ignore time and only compare on date
abbr	boolean	false	true	Set to true to use the abbreviated phrases
language	string	"en"	"nl"	The language code (eg da for Danish) for the language to be used for the output
compare_date	datetime or timestamp	now()	12345	The datetime to compare the other datetime to
round_mode	string	"floor"	"commmon"	Determines how the last outputted value should be rounded. "common" will round up if the remainder is half or more, "ceil" will always round up if there is a remaining part, "floor" not take the remaining part into account
duration	boolean	false	true	Set to true in case the input a duration (e.g 1235 seconds) instead of a datetime or timestamp. In case the input is a sensor with state_class: duration it will be derived from the sensor automatically
duration_unit	string	"s"	"h"	The unit of measurement in case the input is a duration. Can be "d", "h", "min", "ms", "s", or "μs". In case the input is sensor with state_class: duration it will be derived from the sensor automatically

Example usage: Using a sensor state:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(states('sensor.uptime'), parts=3, not_use=['week', 'millisecond'], time=true, abbr=true, language='nl') }}

This will output something like 10 dg, 2 u en 7 min

Using a last_changed datetime of an entity:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus(states.light.office.last_changed, 2) }}

This will output something like 3 hours and 1 minute

Using the always_show parameter (remove the compare_date parameter to use the current date):

{% set current_date = '2023-12-25' %}
{{ relative_time_plus('2018-12-25', compare_date=current_date, not_use='wk', always_show=['yr', 'mth', 'day'], parts=3) }}

This will output 5 years, 0 months and 0 days

Using a date string:

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus('2023-01-01', parts=2, time=false, not_use=['wk']) }}

This will output something like (assuming the current date is 9th of April 2023) 3 months and 8 days

Using a timestamp sensor

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus('sensor.ha_last_booted', parts=2) }}

Using an input_number which represents a duration in hours

{% from 'relative_time_plus.jinja' import relative_time_plus %}
{{ relative_time_plus('input_number.hours_since_lunch', parts=2, duration=true, duration_unit='h') }}

My language is not suported

You can either issue a PR with the language phrases, or create an issue with all the required phrases (so singular, plural and abbreviated per time section, a combine word and an error text) in an issue.