docs - update general settings, localization, and timezones (#27193)

docs/configuring-metabase/appearance.md

@@ -15,6 +15,8 @@ redirect_from:
 
 Appearance settings give you the option to white label Metabase to match your company’s branding.
 
+If you're looking for date, time, number, or currency formatting, see [Formatting defaults](../data-modeling/formatting.md).
+
 ## Changing Metabase's appearance
 
 Click on the gear icon at the bottom of the navigation sidebar and select **Admin settings** > **Settings** > **Appearance**. Here’s what you can do:

docs/configuring-metabase/localization.md

@@ -6,9 +6,15 @@ redirect_from:
 
 # Languages and localization
 
+The **Localization** settings allow you to set global defaults for your Metabase instance. You can find **Localization** under **Admin settings** > **Settings**.
+
+## Default language
+
+Here you can set the default language (also called the "instance language") across your Metabase UI, system [emails](./email.md), [dashboard subscriptions](../dashboards/subscriptions.md), and [alerts](../questions/sharing/alerts.md). People can pick a different language from their own [account settings](../people-and-groups/account-settings.md).
+
 ## Supported languages
 
-Thanks to our amazing user community, Metabase has been translated into many different languages. Due to [the way we collect translations](#policy-for-adding-and-removing-translations), languages may be added or removed during major releases depending on translation coverage.
+Thanks to our amazing user community, Metabase has been translated into many different languages. Due to [the way we collect translations](#translations), languages may be added or removed during major releases depending on translation coverage.
 
 The languages you can currently pick from are:
 
@@ -38,52 +44,60 @@ The languages you can currently pick from are:
 - Ukrainian
 - Vietnamese
 
-## Policy for adding and removing translations
+## Translations
 
-Our community contributes to Metabase translations on our [POEditor project][metabase-poe]. If you'd like to help make Metabase available in a language you're fluent in, we'd love your help!
+Our community contributes to Metabase translations on our [POEditor project](https://poeditor.com/join/project/ynjQmwSsGh). If you'd like to help make Metabase available in a language you're fluent in, we'd love your help!
 
-For a new translation to be added to Metabase, it must reach 100%. Once it does, we add it in the next major or minor release of Metabase. All _existing_ translations in Metabase _must stay at 100%_ to continue being included in the next _major_ version of Metabase. This rule ensures that no one encounters a confusing mishmash of English and another language when using Metabase.
+For a new language to be added to Metabase, it must reach 100%. Once it does, we add it in the next major or minor release of Metabase. All _existing_ languages in Metabase _must stay at 100%_ to continue being included in the next _major_ version of Metabase. This rule ensures that no one encounters a confusing mishmash of English and another language when using Metabase.
 
 We understand that this is a high bar, so we commit to making sure that before each major release, any additions or changes to text in the product are completed at least 10 calendar days before the release ships, at which point we notify all translators that a new release will be happening soon.
 
 Note that while we only remove languages in major releases, we are happy to add them back for minor releases, so it's always a good time to jump in and start translating.
 
-[metabase-poe]: https://poeditor.com/join/project/ynjQmwSsGh
+## Report timezone
 
-## Localization
+Use **report timezone** to set a default display time zone for dates and times in Metabase. The report timezone setting is a display setting only, so changing the report timezone won't affect the time zone of any data in your database.
 
-The **Localization** settings allow you to set global defaults for your Metabase instance. Localization settings include options for:
+Report timezone doesn't apply to `timestamp without time zone` data types, including the output of [`convertTimezone`](../questions/query-builder/expressions/converttimezone.md) expressions. For example:
 
-- **Language**
-- **Date and time**
-- **Numbers**
-- **Currency**
+| Raw timestamp in your database           | Data type                     | Report time zone | Displayed as           |
+| ---------------------------------------- | ----------------------------- | ---------------- | ---------------------- |
+| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | `timestamp with time zone`    | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
+| `2022-12-28T12:00:00-06:00`              | `timestamp with offset`       | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
+| `2022-12-28T12:00:00`                    | `timestamp without time zone` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
 
-The **Localization** settings can be found in the **Admin Panel** under the **Settings** tab.
+Report timezone is only supported for the following databases:
+   - BigQuery
+   - Druid
+   - MySQL
+   - Oracle
+   - PostgreSQL
+   - Presto
+   - Vertica
 
-### Instance language
+## First day of the week
 
-The default language for all users across the Metabase UI, system emails, pulses, and alerts. Users can pick a different language from their own account settings page.
+If you need to, you can change the first day of the week for your instance (the default is Sunday). Setting the first day of the week affects things like grouping by week and filtering in questions built using the [query builder](../questions/query-builder/introduction.md). This setting doesn't affect [SQL queries](../questions/native-editor/writing-sql.md).
 
-### First day of the week
+## Localization options
 
-If you need to, you can change the first day of the week for your instance (the default is Sunday). Setting the first day of the week affects things like grouping by week and filtering in questions built using the [query builder](../questions/query-builder/introduction.md). This setting doesn't affect [SQL queries](../questions/native-editor/writing-sql.md).
+**Localization options** allow you to set global default display formats for dates, times, numbers, and currencies.
 
-### Localization options
+You can also override these localization options for specific fields or questions. For more info, see [Formatting](../data-modeling/formatting.md).
 
-**Dates and Times**
+### Dates and times
 
-- `Date style:` the way dates should be displayed in tables, axis labels, and tooltips.
-- `Date separators:` you can choose between slashes, dashes, and dots here.
-- `Abbreviate names of days and months:` whenever a date is displayed with the day of the week and/or the month written out, turning this setting on will display e.g. `January` as `Jan` or `Monday` as `Mon`.
-- `Time style:` this lets you choose between a 12-hour or 24-hour clock to display the time by default where applicable.
+- **Date style:** the way dates should be displayed in tables, axis labels, and tooltips.
+- **Date separators:** you can choose between slashes (`2022/12/14`), dashes (`2022-12-14`), and dots (`2022.12.14.`).
+- **Abbreviate names of days and months:** whenever a date is displayed with the day of the week and/or the month written out, turning this setting on will display e.g. "January" as "Jan" or "Monday" as "Mon".
+- **Time style:** choose to display the time using either a 12 or 24-hour clock (e.g., 3:00 PM or 15:00).
 
-**Numbers**
+### Numbers
 
-- `Separator style:` some folks use commas to separate thousands places, and others use periods. Here's where you can indicate which camp you belong to.
+- **Separator style:** some people use commas to separate thousands places, and others use periods. Here's where you can indicate which camp you belong to.
 
-**Currency**
+### Currency
 
-- `Unit of currency:` if you do most of your business in a particular currency, you can specify that here.
-- `Currency label style:` whether you want to have your currencies labeled with a symbol, a code (like `USD`), or its full name.
-- `Where to display the unit of currency:` this pertains specifically to tables, and lets you choose if you want the currency labels to appear only in the column heading, or next to each value in the column.
+- **Unit of currency:** if you do most of your business in a particular currency, you can specify that here.
+- **Currency label style:** whether you want to have your currencies labeled with a symbol, a code (like "USD"), or its full name.
+- **Where to display the unit of currency:** this pertains specifically to tables, and lets you choose if you want the currency labels to appear only in the column heading, or next to each value in the column.

docs/configuring-metabase/settings.md

@@ -8,54 +8,48 @@ redirect_from:
 
 This section contains settings for your whole instance, like its URL, the reporting timezone, and toggles for disabling or enabling some of Metabase's optional features.
 
-You can configure these settings in the **General** section of the **Settings** tab in the **Admin Panel**.
+You can configure these settings from **Settings** > **Admin Settings** > **General**.
 
-## Site Name
+## Site name
 
 How you’d like to refer to this instance of Metabase.
 
 ## Site URL
 
-The base URL of this Metabase instance. The base URL is used in emails to allow users to click through to their specific instance. Make sure to include http:// or https:// to make sure it’s reachable.
+The site URL is the web address that people use to access your Metabase instance. Make sure to include `http://` or `https://` to make sure it’s reachable.
 
-## Redirect to HTTPS
+### Redirect to HTTPS
 
-Force all traffic to use HTTPS via redirect, if the site can serve over HTTPS.
+By default, Metabase is served over HTTP.
 
-_Default: disabled_.
+To force all traffic to use HTTPS via redirect, click `http://` (under the **Site URL** section) and select `https://` from the dropdown menu.
 
-For example, if you are serving your Metabase application at "example.com", and you enable HTTPS redirect, when a user enters an address like "example.com/data" in their browser's address bar, the user will be automatically redirected to a secure connection at `https://example.com/data`.
+For example, say you enable HTTPS redirect for a Metabase instance at the site URL "example.com". When someone enters an address like `example.com/data` in their browser's address bar, they'll get automatically redirected to a secure connection at `https://example.com/data`.
 
 > Note: if you haven't set up HTTPS on your server, Metabase will not let you enable HTTPS redirect. Instead, you'll get a warning saying "It looks like HTTPS is not properly configured."
 
-## Email Address for Help Requests
+## Email address for help requests
 
 This email address will be displayed in various messages throughout Metabase when users encounter a scenario where they need assistance from an admin, such as a password reset request.
 
 ## Approved domains for notifications
 
-Allowed email address domain(s) for new [dashboard subscriptions](../dashboards/subscriptions.md) and [alerts](../questions/sharing/alerts.md). To specify multiple domains, separate each domain with a comma, with no space in between (e.g., `domain1,domain2`). To allow all domains, leave the field empty. This setting doesn't affect existing subscriptions.
+Allowed email address domain(s) for new [dashboard subscriptions](../dashboards/subscriptions.md) and [alerts](../questions/sharing/alerts.md). To specify multiple domains, separate each domain with a comma, with no space in between (e.g., "domain1,domain2"). To allow all domains, leave the field empty. This setting doesn't affect existing subscriptions.
 
-## Report Timezone
+## Anonymous tracking
 
-The **report timezone** sets the default time zone for displaying times. The timezone is used when breaking out data by dates.
+This option turns determines whether or not you allow [anonymous data about your usage of Metabase](../installation-and-operation/information-collection.md) to be sent back to us to help us improve the product. [Your database’s data is never tracked or sent](https://www.metabase.com/security).
 
-_Setting the default timezone will not change the timezone of any data in your database_. If the underlying times in your database aren't assigned to a timezone, Metabase will use the report timezone as the default timezone.
+## Friendly table and field names
 
-## Anonymous Tracking
+By default, Metabase attempts to make field and table names more readable by changing things like `somehorriblename` to `Some Horrible Name`. This does not work well for languages other than English, or for fields that have lots of abbreviations or codes in them. If you'd like to turn this setting off, you can do so from the Admin Panel under **Settings** > **Admin settings** > **General**.
 
-This option turns determines whether or not you allow [anonymous data about your usage of Metabase](../installation-and-operation/information-collection.md) to be sent back to us to help us improve the product. _Your database’s data is never tracked or sent_.
+To manually label field or table names in Metabase, check out the [Data Model](../data-modeling/metadata-editing.md) section in your admin settings.
 
-## Enable X-rays
-
-[X-rays](../exploration-and-organization/x-rays.md) are a great way to allow your users to quickly explore your data or interesting parts of charts, or to see a comparison of different things. But if you're dealing with data sources where allowing users to run x-rays on them would incur burdonsome performance or monetary costs, you can turn them off here.
-
-## Enabled Nested Queries
+## Enable nested queries
 
 By default, Metabase allows your users to use a previously saved question as a source for queries. If you have a lot of slow running queries, you may want to switch this option off, as performance problem can occur.
 
-## Friendly Table and Field Names
-
-By default, Metabase attempts to make field and table names more readable by changing things like `somehorriblename` to `Some Horrible Name`. This does not work well for languages other than English, or for fields that have lots of abbreviations or codes in them. If you'd like to turn this setting off, you can do so from the Admin Panel under Settings > General > Friendly Table and Field Names.
+## Enable X-rays
 
-To manually fix field or table names if they still look wrong, you can go to the Metadata section of the Admin Panel, select the database that contains the table or field you want to edit, select the table, and then edit the name(s) in the input boxes that appear.
+[X-rays](../exploration-and-organization/x-rays.md) are a great way for people to get quick summary stats on your data. If these X-ray queries get too slow or expensive, you can turn them off here.

docs/configuring-metabase/timezones.md

@@ -8,6 +8,8 @@ redirect_from:
 
 Metabase does its best to ensure proper and accurate reporting in whatever timezone you desire, but timezones are a complicated beast so it's important to abide by some recommendations listed below to ensure your reports come out as intended.
 
+## Time zone settings
+
 The following places where timezones are set can all impact the data you see:
 
 - `Database` - includes global database timezone settings, specific column type settings, and even individual data values.
@@ -15,14 +17,31 @@ The following places where timezones are set can all impact the data you see:
 - `Metabase` - inside Metabase the reporting timezone setting (if set) will influence how your data is reported.
 - `Metabase Cloud` - if you need to change the timezone on the server that hosts your Metabase Cloud instance, please [contact support](https://www.metabase.com/help-premium).
 
+## Recommended settings
+
 To ensure proper reporting it's important that timezones be set consistently in all places. Metabase recommends the following settings:
 
-- Make sure all of your database columns are properly setup to include timezone awareness.
-- Unless you have a special need it's best to set your database reporting timezone to UTC and store all of your date/time related values in UTC.
+- Make sure all of your database columns are properly setup to include [time zone awareness](#data-types).
+- Unless you have a special need it's best to set your database reporting time zone to UTC and store all of your date/time related values in UTC.
 - Configure your JVM to use the same timezone you want to use for reporting, which ideally should also match the timezone of your database.
 - Set the Metabase `Report Timezone` to match the timezone you want to see your reports in, again, this should match the rest of the timezone settings you've made.
 
-Common Pitfalls:
+## Data types
+
+You can make your database columns time zone aware by storing them as specific data types, such as:
+
+| Data type                     | Description                               | Example                                              |
+| ----------------------------- | ----------------------------------------- | ---------------------------------------------------- |
+| `timestamp with time zone`    | Knows about location.                     | `2022-12-28T12:00:00 AT TIME ZONE 'America/Toronto'` |
+| `timestamp with offset`       | Knows about the time difference from UTC. | `2022-12-28T12:00:00-04:00`                          |
+| `timestamp without time zone` | No time zone info.                        | `2022-12-28T12:00:00`                                |
+
+The exact data type will depend on your database. Some Metabase features only work with specific data types:
+
+- [Report timezone setting](../configuring-metabase/localization.md#report-timezone)
+- [`converttimezone` custom expression](../questions/query-builder/expressions/converttimezone.md)
+
+## Common pitfalls
 
 1. Your database is using date/time columns without any timezone information. Typically when this happens your database will assume all the data is from whatever timezone the database is configured in or possible just default to UTC (check your database vendor to be sure).
 2. Your JVM timezone is different from your Metabase `Report Timezone` choice. This is a very common issue and can be corrected by launching java with the `-Duser.timezone=<timezone>` option properly set to match your Metabase report timezone.

docs/questions/query-builder/expressions/converttimezone.md

@@ -129,11 +129,11 @@ Metabase displays timestamps without time zone or offset information, which is w
 
 The Metabase report time zone only applies to `timestamp with time zone` or `timestamp with offset` data types. For example:
 
-| Raw timestamp                            | Report time zone | Displayed As           |
-| ---------------------------------------- | ---------------- | ---------------------- |
-| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
-| `2022-12-28T12:00:00-06:00`              | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
-| `2022-12-28T12:00:00`                    | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
+| Raw timestamp in your database           | Data type                     | Report time zone | Displayed as           |
+| ---------------------------------------- | ----------------------------- | ---------------- | ---------------------- |
+| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | `timestamp with time zone`    | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
+| `2022-12-28T12:00:00-06:00`              | `timestamp with offset`       | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM  |
+| `2022-12-28T12:00:00`                    | `timestamp without time zone` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
 
 The Metabase report time zone will not apply to the output of a `convertTimezone` expression. For example:
 

docs/troubleshooting-guide/timezones.md

@@ -44,14 +44,8 @@ Once you think you have identified a problem, drill down to understand exactly w
 
 **Steps to take:**
 
-1. Go to the Admin Panel, select the **Localization** tab, and check the **Report Time Zone** setting, which controls the timezone Metabase uses when connecting to the database. This setting is currently supported on:
-   - Druid
-   - MySQL
-   - Oracle
-   - PostgreSQL
-   - Presto
-   - Vertica
-2. If you're using a database that doesn't support a Report Time Zone, ensure that Metabase's time zone matches that of the database. Metabase's time zone is the Java Virtual Machine's time zone, typically set via a `-Duser.timezone<..>` parameter or the `JAVA_TIMEZONE` environment variable; exactly how it is set will depend on how you launch Metabase. Note that Metabase's time zone doesn't impact any databases that use a Report Time Zone.
+1. Check the [report timezone setting](../configuring-metabase/localization.md#report-timezone) from **Admin settings** > **Settings** > **Localization**.
+2. If you're using a database that doesn't support the report timezone setting, ensure that Metabase's time zone matches that of the database. Metabase's time zone is the Java Virtual Machine's time zone, typically set via a `-Duser.timezone<..>` parameter or the `JAVA_TIMEZONE` environment variable; exactly how it is set will depend on how you launch Metabase. Note that Metabase's time zone doesn't impact any databases that use a Report Time Zone.
 
 ## Are SQL queries not respecting the Reporting Time Zone setting?
 
@@ -59,7 +53,15 @@ Once you think you have identified a problem, drill down to understand exactly w
 
 **Steps to take:**
 
-1. Set a reporting time zone explicitly in your SQL query.
+Set a reporting time zone explicitly in your SQL query.
+
+For example, you can write something like this with PostgreSQL:
+
+```sql
+SELECT column::TIMESTAMP AT TIME ZONE 'EST' AS column_est
+```
+
+This statement casts the column to a `timestamp` data type first, then converts the `timestamp` into a `timestamptz` data type, with time zone 'EST'.
 
 ## Are dates without an explicit time zone being converted to another day?