Docs: Handling timezones inside email templates

[DanielBiegler]

Is your feature request related to a problem? Please describe.

Vendure saves dates in UTC which should be converted to the customers/users local timezone inside of emails. This is easy enough if you sell to only one region, like for example central europe, but this becomes a bit trickier once expanding or even for singular, larger countries (USA, Canada, ...) with multiple timezones inside the same shipping area.

Describe the solution you'd like

It'd be nice to have an example in the docs that uses the customers address to look up the relevant timezone and then pass that info into the EmailPlugin so that a datetime can be formatted correctly.

Additional context

Theres a maintained timezone database by IANA here which inside of the tzdata*.tar.gz archive features a countries_with_timeZones.json file which has entries that look like this:

[
  {
    "IsoAlpha3": "DEU",
    "TimeZones": ["Europe/Berlin", "Europe/Busingen"],
    "WindowsTimeZones": [
      {
        "Id": "W. Europe Standard Time",
        "Name": "(UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna"
      }
    ],
    "CountryName": "Germany",
    "IsoAlpha2": "DE"
  }
]

Adresses have a Country field which extends Region which have a code column which usually features a two character ISO country code that could be used to look up the timezones.

This would solve the problem for smaller countries with a single timezone, but leaves larger countries hanging. See the "US" entry:

  {
    "IsoAlpha3": "USA",
    "TimeZones": [
      "America/New_York",
      "America/Detroit",
      "America/Kentucky/Louisville",
      "America/Kentucky/Monticello",
      "America/Indiana/Indianapolis",
      "America/Indiana/Vincennes",
      "America/Indiana/Winamac",
      "America/Indiana/Marengo",
      "America/Indiana/Petersburg",
      "America/Indiana/Vevay",
      "America/Chicago",
      "America/Indiana/Tell_City",
      "America/Indiana/Knox",
      "America/Menominee",
      "America/North_Dakota/Center",
      "America/North_Dakota/New_Salem",
      "America/North_Dakota/Beulah",
      "America/Denver",
      "America/Boise",
      "America/Phoenix",
      "America/Los_Angeles",
      "America/Anchorage",
      "America/Juneau",
      "America/Sitka",
      "America/Metlakatla",
      "America/Yakutat",
      "America/Nome",
      "America/Adak",
      "Pacific/Honolulu"
    ],
    "WindowsTimeZones": [
      {
        "Id": "Eastern Standard Time",
        "Name": "(UTC-05:00) Eastern Time (US & Canada)"
      },
      {
        "Id": "US Eastern Standard Time",
        "Name": "(UTC-05:00) Indiana (East)"
      },
      {
        "Id": "Central Standard Time",
        "Name": "(UTC-06:00) Central Time (US & Canada)"
      },
      {
        "Id": "Mountain Standard Time",
        "Name": "(UTC-07:00) Mountain Time (US & Canada)"
      },
      { "Id": "US Mountain Standard Time", "Name": "(UTC-07:00) Arizona" },
      {
        "Id": "Pacific Standard Time",
        "Name": "(UTC-08:00) Pacific Time (US & Canada)"
      },
      { "Id": "Alaskan Standard Time", "Name": "(UTC-09:00) Alaska" },
      { "Id": "Hawaiian Standard Time", "Name": "(UTC-10:00) Hawaii" }
    ],
    "CountryName": "United States",
    "IsoAlpha2": "US"
  },

Additional Links

• Docs: EmailEventHandler
• Partly relevant issue Add timezone property to Channel for datetime inputs #183 which thought about adding a timezone field to channels

[DanielBiegler]

This could also be a larger discussion about introducing a timezone field on the User Entity because this seems to be generally useful IMO. Other shop systems, CRMs, CMSs, etc. often feature a timezone field on users. Thinking out loud here.