Get user locale and timezone

Google Workspace Add-ons can access the locale and timezone of its user and use that information to customize its interface and behavior. You must configure your add-on's manifest to permit your add-on to access this information.

Configure the add-on manifest

You can configure your add-on to access user locale and timezone information with the following steps:

1. In your add-on's manifest file, set the addOns.common.useLocaleFromApp field to true.
2. If it isn't present already, add the following explicit scope in the manifest's oauthScopes list: https://www.googleapis.com/auth/script.locale

If you added a scope to the add-on's oauthScope list, users must re-authorize the add-on the next time it is opened.

Note: If your add-on previously used the Calendar API, the Apps Script Calendar service, or other service to access the user's locale and timezone, consider whether that service is still needed by your add-on. If not, remove any scopes that service requires from your manifest. Always limit your scope list to only those services that your add-on needs.

Get locale and timezone information

Event objects carry user locale information when properly configured. The following fields appear in the commonEventObject substructure of the event object:

• commonEventObject.userLocale—The user's language and country/region identifier. For example, en-US.
• commonEventObject.timeZone.offset—The user's timezone offset, in milliseconds, from Coordinated Universal Time (UTC).
• commonEventObject.timeZone.id—The user's timezone identifier. For example, America/New_York.
• commonEventObject.timeZone—The user's timezone ID and offset.

See Event objects for more details.

Event objects are passed to action callback functions as the user interacts with your add-on, and to homepage and contextual trigger functions. Each callback or trigger function can read the locale and timezone information from the event object and use it as necessary. For example, a callback function that is navigating to a new card could refer to the locale string when deciding what text to add to the card.