Add FidesLocaleUpdated event to monitor locale changes and improve documentation

[gilluminate]

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.

Code Changes

• Added FidesLocaleUpdated event that fires 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

Ticket

ENG-1780

Steps to Confirm

1. Load the fides-js demo page at http://localhost:3001/fides-js-demo.html
2. Verify the modal link label displays correctly on page load
3. Change the language using the language selector
4. Verify the modal link label updates to match the selected language
5. Check browser console for FidesLocaleUpdated event logs

[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 16, 2026 11:44pm
fides-privacy-center	Ignored		Jan 16, 2026 11:44pm

[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