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 TimeZone property is used for parsing date strings, not for automatically converting dates during rendering. To convert dates to a specific timezone for display, use the time_zone filter.

Note: The date filter 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), %x and %X. Day and month names and AM/PM come from the culture. %Z is the zone name like in Ruby: the abbreviation of the context's time zone (EST, CEST, +04) for a time in it, UTC for a UTC time (a DateTime of Utc kind, or a string in Z, UTC or -00:00), +00:00 for a DateOnly, and nothing for a time with another offset, like 12:00 +04:00 in New York. After time_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 (TZDIR or /usr/share/zoneinfo) on Linux and macOS. On Windows, and for custom time zones, the offset is shown instead (-05:00, or UTC for a zero offset). Breaking change: %Z used 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 the format_date filter.

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

Esc to close