Stay organized with collections
Save and categorize content based on your preferences.
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:
In your add-on's manifest
file, set the
addOns.common.useLocaleFromApp
field to true.
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.
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.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-07-30 UTC."],[[["Google Workspace add-ons can be configured to access and utilize a user's locale and timezone for customization."],["Add-on developers must set `addOns.common.useLocaleFromApp` to `true` and include the `https://www.googleapis.com/auth/script.locale` scope in the manifest file for locale and timezone access."],["Event objects provide the user's locale and timezone information through fields like `userLocale`, `timeZone.offset`, and `timeZone.id`, which add-ons can utilize in their functions."],["After adding the necessary scope, users need to re-authorize the add-on for the changes to take effect."],["Add-ons should only request necessary scopes and consider removing unused ones, especially those previously used for locale and timezone access through other APIs or services."]]],["Google Workspace add-ons can access user locale and timezone by configuring the add-on manifest. Set `addOns.common.useLocaleFromApp` to `true` and add `https://www.googleapis.com/auth/script.locale` to `oauthScopes`. This requires users to re-authorize the add-on. Event objects contain `userLocale`, `timeZone.offset`, and `timeZone.id`. Callback functions and trigger functions read this information from the event object to customize the add-on's interface and behavior, such as text on cards.\n"]]
