GuideWriting templates
Cultures, dates and time zones
How the culture and the time zone affect rendering, and how strings are converted to dates.
CultureLink to this heading
By default, templates are rendered using an invariant culture so that the results are consistent across systems. This is important, for instance, when rendering dates, times, and numbers.
However, you can define a specific culture to use when rendering a template using the TemplateContext.CultureInfo property.
SourceLink to this heading
var options = new TemplateOptionsBuilder()
.WithCultureInfo(new CultureInfo("en-US"))
.Build();
var context = new TemplateContext(options);
var result = template.Render(context);
{{ 1234.56 }}
{{ "now" | date: "%A, %B %-d, %Y" }}
ResultLink to this heading
1234.56
Tuesday, August 1, 2017
Ordering stringsLink to this heading
The culture doesn't change how strings are ordered. Like in Shopify, sort and the <, <=, > and >= operators compare strings by code point, so uppercase letters come before lowercase ones and an emoji comes after any other character: {{ "b,a,B,😀,é" | split: "," | sort | join: " " }} renders B a b é 😀.
Dates are ordered too, chronologically, like a Ruby Time or Date: see Comparing dates.
sort_natural compares the lowercase strings the same way, whatever the alphabet: {{ "b,_,É,a,B,é" | split: "," | sort_natural | join: " " }} renders _ a b B É é. Accented letters are still after z, and the characters that are between Z and a in ASCII ([ \ ] ^ _ ` ) are before the letters. Like Ruby's downcase, İ is lowercased to i followed by a combining dot (U+0307), so {{ "İ,j,i,k" | split: "," | sort_natural | join: " " }} renders i İ j k.
Time zonesLink to this heading
For a complete guide on working with time zones, see Working with time zones.
System time zoneLink to this heading
TemplateOptions and TemplateContext provide a property to define a default time zone to use when parsing dates and times. The default value is the current system's time zone. Setting a custom one can also prevent different environments (data centers) from generating different results.
- When dates and times are parsed and don't specify a time zone, the configured one is assumed.
- When a time zone is provided in the source string, the resulting date time uses it.
Strings are converted to dates like Liquid does with Ruby's Time.parse. now and today, in any casing, are the current time, and a string of digits is a number of seconds since 1970, like an integer. A number with a fraction, like 0.5 or 1592222400.0, isn't a date, as Ruby's Time.at is only called with an integer: date returns it unchanged. Other strings can be in many formats: 2020-06-15T12:00:00Z, 2020-06-15 12:00:00 UTC, Mon, 15 Jun 2020 12:00:00 +0100, Fri Jul 16 01:00:00 2004, June 15, 2020, 15 June 2020, 15/06/2020 (day first), 20200615T120000. Zones are offsets like +01:00, Z, UTC, GMT or the US abbreviations (EST, PDT, ...); others, like CET, are ignored. .NET offsets are whole minutes, so an offset with seconds keeps the instant (%s) but drops its seconds from the zone, like %z in Ruby, and moves them to the time: 2020-06-15 12:00:00 +05:30:15 is 11:59:45 +0530. The fields missing before the first one in the string come from the current time ('5 May' is May 5 of this year, '12:30' is today), and strings without a date or time like '1,2,3' are not dates: date returns them unchanged. With a specific culture, the formats of the culture are tried first, so 08/01/2017 is August 1 in en-US and January 8 in fr-FR.
Important: The
TimeZoneproperty is used for parsing date strings, not for automatically converting dates during rendering. To convert dates to a specific timezone for display, use thetime_zonefilter.
Note: The
datefilter conforms to the Ruby date and time formats https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html, including flags, widths and composite formats like%c(%a %b %e %H:%M:%S %Y),%xand%X. Day and month names and AM/PM come from the culture.%Zis the zone name like in Ruby: the abbreviation of the context's time zone (EST,CEST,+04) for a time in it,UTCfor a UTC time (aDateTimeofUtckind, or a string inZ,UTCor-00:00),+00:00for aDateOnly, and nothing for a time with another offset, like12:00 +04:00in New York. Aftertime_zone, it is the abbreviation of that time zone. .NET doesn't expose abbreviations, so they are read from the system's time zone database (TZDIRor/usr/share/zoneinfo) on Linux and macOS. On Windows, and for custom time zones, the offset is shown instead (-05:00, orUTCfor a zero offset). Breaking change:%Zused to be the offset for every time zone, and is now empty for times with an offset that isn't the time zone's. A format that ends inside a conversion (%,%-) is a template error. To use the .NET standard date formats, use theformat_datefilter.
SourceLink to this heading
var context = new TemplateContext { TimeZone = TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time") } ;
var result = template.Render(context);
{{ '1970-01-01 00:00:00' | date: '%c %z' }}
ResultLink to this heading
Thu Jan 1 00:00:00 1970 -0800
Converting time zonesLink to this heading
Dates and times can be converted to specific time zones using the time_zone filter. On .NET 6 and later, identifiers are resolved with TimeZoneInfo.FindSystemTimeZoneById. The netstandard2.0 asset uses TimeZoneConverter by default.
ExampleLink to this heading
var context = new TemplateContext();
context.SetValue("published", DateTime.UtcNow);
{{ published | time_zone: 'America/New_York' | date: '%+' }}
On Windows, IANA identifiers require ICU globalization data. Resolution can fail on Windows versions that do not include ICU unless the application deploys it app-locally with the Microsoft.ICU.ICU4C.Runtime package. IANA identifiers are also unavailable when globalization invariant mode is enabled (System.Globalization.Invariant) or Windows NLS is forced (System.Globalization.UseNls). In these configurations, configure a custom resolver. For example, with the TimeZoneConverter package:
var options = new TemplateOptionsBuilder()
.WithTimeZoneResolver(id => TimeZoneConverter.TZConvert.GetTimeZoneInfo(id))
.Build();
var context = new TemplateContext(options);
ResultLink to this heading
Tue Aug 1 17:04:36 -05:00 2017