Workday manages tenant terminology across two distinct configuration layers—delivered UI term overrides (Maintain Custom Labels / Maintain Non-English Custom Labels) and tenanted business object data translations (Translate Business Object / Translations Hub)—and resolves human-readable descriptor strings in REST, WQL, RaaS, and SOAP responses dynamically according to the authenticated caller’s language and locale hierarchy.
Integrations and custom employee screens break when developers hardcode string comparisons against descriptor values (such as "Vacation" or "Transfer > Move to another Manager"), or wonder why French-Canadian and Spanish workers receive US English plan names when requests run through a single US-English Integration System User instead of user-delegated OAuth 2.0.
Layer 1 vs. Layer 2: Custom UI Labels vs. Tenanted Object Translations
Before reading labels over an API, distinguish where a term actually lives inside Workday configuration:
| Dimension | Delivered UI Label Overrides | Tenanted Business Object Translations | Custom Report & RaaS Labels |
|---|---|---|---|
| DimensionPrimary Admin Tasks | Delivered UI Label OverridesMaintain Custom Labels (English) & Maintain Non-English Custom Labels + Maintain Non-English Custom Label Overrides |
Tenanted Business Object TranslationsEdit Tenant Setup - Global, Translations Hub, Translate Business Object, or globe In-Context Translation icon |
Custom Report & RaaS LabelsRelated Actions on report: Translation > Translate Instance & Custom Report > Translate |
| DimensionRequired Security Domain | Delivered UI Label OverridesCustom Label Management and Custom Label Management for Non-English (System functional area) |
Tenanted Business Object TranslationsData Translation and Data Translation: In-Context Translation (System functional area) |
Custom Report & RaaS LabelsData Translation + Custom Report Administration (System functional area) |
| DimensionWhat It Renames | Delivered UI Label OverridesDelivered platform nouns (singular, plural, possessive) within a Term Context—e.g., Contingent Worker -> Contractor, or Spanish registro de entrada -> registro de ingreso | Tenanted Business Object TranslationsCustomer-created instances: Absence Plan names, Benefit Plan names, Job Change / Termination Reasons, Organizations, Questionnaires, Text Blocks | Custom Report & RaaS LabelsReport Name, Column Heading Overrides, Prompt Labels, Sort Group Overrides, Instructions |
| DimensionEffect on REST / SOAP Schema Keys | Delivered UI Label OverridesNone. Workday does not apply custom labels to security or integration schema property names | Tenanted Business Object TranslationsPopulates descriptor (REST/WQL) and wd:Descriptor (SOAP) in the caller’s resolved display language |
Custom Report & RaaS LabelsTranslates RaaS UI headers/prompts; XML element tags stay fixed to the report’s XML alias |
Critical Nuances on Maintain Custom Labels and Non-English Overrides
- Integrations and Existing Report Titles Stay Unchanged: Workday explicitly does not replace terms inside security administration or integration definitions, and creating a custom label for Contingent Workers does not automatically rename an existing custom report titled Custom Report for Contingent Workers.
- Two-Task Activation for Non-English Custom Labels: When overriding a Workday-delivered term in another language (for example,
Spanish (Neutral)under theTime Corecontext), entering an Override Value and clearing Disabled on Maintain Non-English Custom Labels triggers a background preparation job. Once that job finishes, you must open Maintain Non-English Custom Label Overrides and select Use Proposed Value (or Use All Proposed Values) for the override to appear on self-service tasks (and via theGet_Non-English_Custom_Label_OverridesSOAP operation). - Search Index Timing: Newly saved custom labels appear in Workday search results only after the Friday server restart index rebuild (or an explicit Rebuild Search Index run, which Workday recommends avoiding during peak hours).
How Workday Determines Which Language an API Call Receives
Whenever a caller invokes a Workday REST endpoint, WQL query, RaaS report, or SOAP operation, Workday evaluates a strict six-level fallback chain for the authenticated Run As User to choose which language string populates descriptor fields:
- User’s Selected Preferred Display Language (set via Change Preferences or
Edit Workday Account) - User’s Selected Preferred Locale
- Selected Language of the Worker’s Primary Business Site Location
- Selected Locale of the Worker’s Primary Business Site Location
- Default Language of the Tenant
- Default Locale of the Tenant (typically
English (United States))
Two additional tenant switches govern what happens when a specific plan name or reason code has not been translated into the worker’s target language yet:
- Base Language Fallback &
Allow Mixed-Language Transactions: Every Workday object stores a Base Language (viewable via the Base Languages report). On self-service views, untranslated items may be suppressed unless Allow Mixed-Language Transactions is checked on Edit Workday Account / Manage Workday Accounts (or no translation exists for a text block, in which case Workday falls back to the base language). - Base Value Edits (
Hide Translations after Base Value Change): On Edit Tenant Setup - Global, if Hide Translations after Base Value Change is checked and an admin edits the English base name of a Time Off Plan or Question, Workday clears the active translation (Needs Translationstatus on Translate Business Object). Note also that for Effective-Dated Snapshot objects (such asOrganization), creating a new effective-dated snapshot copies existing translations forward, whereas editing the base value on an existing translated snapshot deletes its translations.
[!IMPORTANT] Why User-Delegated OAuth Fixes Multilingual Self-Service Automatically If your external portal or assistant queries Workday through a shared Integration System User (RaaS user-delegated OAuth vs. ISU Basic Auth), every worker receives
descriptorstrings in the ISU’s language (almost always US English). When each worker authenticates via Register API Client (Authorization Code Grant with PKCE), Workday evaluates that worker’sPreferred Display Languageand primary work location automatically—returning French, German, Spanish, or Japanese plan and reason names with zero external translation tables to maintain.
Reading Plan Names, Reason Codes, and Descriptors Across REST, WQL, and SOAP
Across every Workday API surface, Workday pairs an immutable identifier (id / WID or Reference_ID) with a localized human label (descriptor / @wd:Descriptor).
1. Workday REST APIs (absenceManagement, common, staffing)
Every object reference in a Workday REST response contains id (the 32-character Workday ID) and descriptor (localized for the current OAuth caller). Compare what GET /common/v1/jobChangeReasons or GET /absenceManagement/v5/workers/me/eligibleAbsenceTypes returns for two workers in the same tenant:
// Worker A (Preferred Display Language: English)
{
"data": [
{
"id": "a18c426056a1100018b52d4e99c10042",
"descriptor": "Annual Paid Vacation (Hours)"
},
{
"id": "b7187dceedb34c8db3a8e15adf02a620",
"descriptor": "Transfer > Transfer > Move to another Manager"
}
]
}// Worker B (Preferred Display Language: French - Canada, translated via Translate Business Object)
{
"data": [
{
"id": "a18c426056a1100018b52d4e99c10042",
"descriptor": "Vacances annuelles payées (Heures)"
},
{
"id": "b7187dceedb34c8db3a8e15adf02a620",
"descriptor": "Mutation > Mutation > Changement de gestionnaire"
}
]
}Notice that id (a18c426056a1100018b52d4e99c10042) is identical across both languages, including hierarchical Category > Subcategory > Reason strings configured on Maintain Event Categories and Reasons.
2. Workday Query Language (WQL)
When querying WQL (/ccx/api/wql/v1/{tenant}/data), selecting any business object reference field returns { "id": "...", "descriptor": "..." } localized to the authenticated caller:
SELECT timeOffPlan,
timeOffType,
unitOfTime
FROM eligibleTimeOffPlansForWorkerRule for WHERE Clauses: Never write WHERE timeOffPlan = 'Annual Paid Vacation' in WQL or filter arrays in TypeScript by item.descriptor.includes("Vacation"). Filter by immutable WID or Reference_ID so renaming a plan on Edit Time Off Plan or switching user locales never breaks query predicates.
3. Workday Web Services (SOAP)
In SOAP responses (for example, Get_Time_Off_Plans in Absence_Management or Get_Workers in Human_Resources; see calling SOAP with user-delegated Bearer credentials), Workday includes the wd:Descriptor XML attribute on *_Reference elements when descriptors are not suppressed in the request header:
<wd:Time_Off_Plan_Reference wd:Descriptor="Vacances annuelles payées (Heures)">
<wd:ID wd:type="WID">a18c426056a1100018b52d4e99c10042</wd:ID>
<wd:ID wd:type="Absence_Plan_ID">PTO_ANNUAL_HRS</wd:ID>
</wd:Time_Off_Plan_Reference>Keep <wd:Include_Reference_Descriptors_In_Response>true</wd:Include_Reference_Descriptors_In_Response> inside bsvc:Workday_Common_Header whenever your application renders reference labels directly from SOAP responses.
Audit Checklist for Missing or Stale Translated Labels
- Verify Language Enablement: Open Edit Tenant Setup - Global and confirm the target language has Enabled checked in the Available Languages grid.
- Audit Base Value Resets: Run the Translation Base Value Change Audit report (or View Translatable Values for Language / Search Translatable Text from Translations Hub) to catch plan names or reasons stuck in
Needs TranslationorNeeds Reviewafter an English copy edit. - Check Location vs. User Preference: Remember that localized country-specific fields (such as
Maintain Local Termination Reasonsor custom country names onMaintain Workday Delivered Country Names) filter availability by the worker’s primary work location, whereas the text translation of those values follows the worker’s Preferred Display Language. - Test Under Real Worker Sessions: Sign in as a test worker whose Preferred Display Language is set to Spanish or French via user-delegated OAuth—or build multilingual employee screens in Kiweely Leaf (coming next), which reads each signed-in worker’s live tenant terminology and translated descriptors automatically without duplicating translation dictionaries outside Workday.
Frequently asked questions
Does Maintain Custom Labels change SOAP XML element names or REST JSON property keys?
No. Workday explicitly excludes security and integration schemas from Maintain Custom Labels overrides so API contracts remain stable. Overriding Contingent Worker to Contractor changes self-service UI labels, not JSON keys or WSDL element names.
Why did editing the English name of an Absence Plan or Question clear its French and Spanish translations?
When Hide Translations after Base Value Change is checked on Edit Tenant Setup - Global, editing the base language value of a tenanted translatable attribute clears its active display status and marks existing translations as Needs Translation until reviewed on Translate Business Object.
Why does a RaaS report or REST API return English plan names when called through an Integration System User?
Workday resolves object descriptors and custom report labels using the authenticated Run As User's Preferred Display Language and Locale hierarchy. Because an Integration System User typically defaults to US English, calling via an ISU strips individual worker language preferences—whereas user-delegated OAuth returns descriptors in each signed-in worker's language.
Should external applications filter business logic on the descriptor string or on the Workday ID / Reference ID?
Always key programmatic logic on the 32-character Workday ID (id) or Reference ID, and treat descriptor / @Descriptor strictly as a localized human display label. Descriptor strings change whenever a user switches display languages or an admin renames a plan.