Add FidesLocaleUpdated event to monitor locale changes and improve documentation

[gilluminate]

Ticket: ENG-1780

Description

Previously, the recommended pattern would result in the modal link label not updating when users changed their language preference. Adds FidesLocaleUpdated event to support this. Updated getModalLinkLabel() documentation and implementation to properly handle locale changes.

Even though "fides-modal-link" has always been our default value for modalLinkID, it never showed up that way in Fides.options. This PR also updates the way we set that default to be more accessible to customers.

Several other race condition fixes to ensure locale is respected during and after page load.

Code Changes

• Added FidesLocaleUpdated event that fires during pageload and when locale changes
• Updated LanguageSelector component to dispatch locale change events
• Improved documentation with correct event listener pattern
• Changed modalLinkId type from string | null to string with default value
• Updated demo page to use the new event-driven pattern

Steps to Confirm

1. Set up a US, a TCF, and a headless experience
2. Ensure each experience has a translation set for "Trigger link label" (eg. in the german language use "Einstellungen verwalten")
3. In Chrome dev tools, go to Kabab menu -> More Tools -> Sensors and Change location to get the locale set in the browser (eg. Berlin to get the de-DE locale set)
4. Load the fides-js demo page for each experience's location (eg. http://localhost:3001/fides-js-demo.html?geolocation=eea for TCF, etc.)
5. Verify the modal link label displays the translated value on page load
6. Change the language using the language selector in the banner and/or modal
7. Verify the modal link label updates to match the selected language

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
fides-plus-nightly	Ignored	Preview	Jan 26, 2026 5:39pm
fides-privacy-center	Ignored		Jan 26, 2026 5:39pm

[gilluminate]

This got missed when we first implemented the min/full experience split on TCF.

[greptile-apps]

Greptile Summary

This PR adds a new FidesLocaleUpdated event that fires when users change their language preference, solving the issue where modal link labels wouldn't update dynamically. The implementation also improves the modalLinkId default value handling by changing it from string | null to string with a guaranteed default of "fides-modal-link", making it more accessible to customers in Fides.options.

Key changes:

• Added FidesLocaleUpdated event with dispatchLocaleEvent() function
• Updated language selector to dispatch locale events when changed
• Improved documentation with correct event-driven pattern for updating modal links
• Changed modalLinkId type to string with DEFAULT_MODAL_LINK_ID constant
• Updated demo page to demonstrate the new event listener pattern
• Fixed locale event dispatching for both regular and TCF overlays as well as headless mode

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The implementation is well-designed with proper event dispatching, comprehensive documentation, and consistent handling across all code paths (regular overlay, TCF overlay, and headless mode). The type change from string | null to string improves type safety and makes the default value more discoverable. All changes are backwards compatible and follow existing patterns in the codebase.
• No files require special attention

Important Files Changed

Filename	Overview
clients/fides-js/src/lib/events.ts	Added FidesLocaleUpdated event and dispatchLocaleEvent function to notify listeners when locale changes
clients/fides-js/src/lib/i18n/i18n-context.tsx	Updated setCurrentLocale callback to dispatch locale change events when language is changed
clients/fides-js/src/lib/consent-types.ts	Changed modalLinkId type from `string
clients/fides-js/src/lib/initialize.ts	Added dispatchLocaleEvent call for headless component to ensure locale event fires when modal link is found
clients/privacy-center/public/fides-js-demo.html	Updated demo to use event-driven pattern with FidesLocaleUpdated listener instead of manual polling
clients/fides-js/src/docs/fides-event.ts	Added comprehensive documentation for new FidesLocaleEvent interface

[jpople]

Tested locally, link label is correct based on browser location and updates as expected. Nice work!