[Bug:] i18n appears to be broken

[sydk-adhoc]

Describe the Bug

MCT recently adopted the CMSDS Pagination component. It contains overridable translations for Previous and Next links, but the mobile-viewport-width content Page {X} of {XX} is not controlled by a prop, and only uses the CMSDS internal translation helper, t.

MCT uses both the setLanguage helper from CMSDS and also updates the html element's lang attribute anytime a user changes language using the switch in the MAX global header. But the component is not updating its content to reflect the language set using the helper or derived from the html lang attribute.

See code here and observe the value of the html lang attribute when switching from English to Spanish and back.

To reproduce

• Go to https://imp.medicare.gov/plan-compare
• Enter 21224
• Select MA plans
• Choose no extra help (low-income subsidy)
• Choose to add no drugs
• Choose to add no providers
• On the plans results page, open devtools, narrow the viewport down to mobile-device width, scroll down to where the pagination component is rendered and showing Page 1 of 3 (or similar)
• Scroll to the top, open the mobile menu using the hamburger icon, and choose "Cambiar a Espanol"
• Scroll back to the bottom and observe that Page 1 of 3 has not changed to Spanish

Expected behavior

Either changing the html lang attribute (from en to es or vice-versa) or calling CMSDS's setLanguage helper with either en or es, or both, should update CMSDS components' internal translations.

Severity/Impact

High: Affects PI objectives, breaks 508 compliance, breaks application

Desktop Operating System

Mac OS

Desktop Browser Name

Chrome

Desktop Browser Version

149.0.7827.54

Device

N/A

Mobile Operating System

N/A

Mobile Browser Name

N/A

Mobile Browser Version

N/A

Additional context

I have tried all variations of using html lang or the CMSDS language helpers (one, not the other, both, choosing to update the URL with a lang query parameter or not -- we do), and no combination of changes trigger the Pagination component to update its internally translated content.

Codebase/Repository URL

https://github.com/CMSgov/oc-mct-frontend

Design System Version

Medicare 14.4.5

Existing branch or Pull request on Github

N/A

Team Name

MCT

[sydk-adhoc]

New learning and workaround, although I think there's still a bug that needs fixing:

For Pagination, if I add the global HTMLElement attribute lang as a prop, it appears to get passed in and set on the top-level element of the rendered component. I'm setting this to the value that we keep in MCT context, and which we also pass to CMSDS setLanguage and update on the html element's (document.documentElement's) lang attribute. But the only thing that seems to work is passing lang directly to the component, which is a win, for now.

[jack-ryan-nava-pbc]

This is interesting @sydk-adhoc because while I can replicate the failure on the production site, I can't replicate it in our Storybook or Astro React 19 example project.

[jack-ryan-nava-pbc]

@sydk-adhoc how does that lang attribute work? I'm wondering if there's something going on with the pagination component that is preventing it from re-rendering when the language is changed and that by adding the lang as a prop you're just changing the props and then triggering a re-render?

The language value always comes from the document language, which our setLanguage function does not update. We just set a global language variable.

[jack-ryan-nava-pbc]

Updating the html element and the language variable won't by themselves re-render the component, which is what needs to happen (at least I'm pretty sure) to pull in the new language settings.

Sorry if you know all of this already, I'm trying to catch up!

[sydk-adhoc]

Hi, @jack-ryan-nava-pbc.

So, from the CMSDS docs:

For applications that have a lang attribute on their html element, the language will be detected automatically. If that language is not English or Spanish, the language of the design system will fall back to English. If automatic language detection does not work for your use case, the language can be set manually through the setLanguage function. Similarly, the current language can also be read from the getLanguage function. Here's an example:

What we do, at a very high level in our React app is a) sync a lang query parameter and React context to the current, user-chosen language, which propagates through our page/component tree, b) update the lang attribute on the html element, and c) call setLanguage with the current language set in the URL, context, and on the lang attribute of html. So I think we're just trying to cover all the bases.

From reading the docs, my thought was that the DS must have a built-in MutationObserver on html. As you say, just updating that attribute by itself shouldn't cause anything to happen, but my assumption was that some mechanism must be built into the DS, or that wouldn't even be mentioned in the docs. But maybe I'm misreading it?

setLanguage is part of the CMSDS api, yet also doesn't seem to do what we need. The only thing that's worked for me is to update the lang attribute on the component itself, using our context value, and that makes sense given that it guarantees the component will rerender. But even that approach isn't documented, from what I can find.

I think many components may not pass down default HTML attributes or even expose them as props. E.g., I just randomly dropped a Drawer in one of our page components and tried to add lang to it, and it's not a typed prop for that component. Maybe it's only exposed for components that contain internal translations?

I'd say at a minimum the documentation could be a little clearer about this, but if the expected way to make translations work is to pass lang to a CMSDS component, that should be the main or only documented approach, and it should be clear what components can take that prop and which can't.

[jack-ryan-nava-pbc]

I'm starting to think that we should break the translation documentation out into it's own section on the Doc Site.

One thing I do want to note is that we have a getLanguage function. It's not explicit or clear from the documentation but it seems to me that these two functions are meant to be used in conjunction. setLangauge maybe being called in an onClick event, and then getLanguage being called in a useEffect or something.

For this case, passing the lang attribute into pagination is valid HTML, as those additional props are spread onto the underlying nav element. And it looks like lang can be set on any HTML element.

I don't think we want folks to have to pass lang as an attribute to individual components, unless they explicitly want a case where there is a divergence in translation. Most apps seem to handle translations at the page level.

As the above HTML spec notes, lang is computed node by node and checks the value of the attribute on the parent node if it is not set on the current node. If I'm reading that correctly then passing in a lang attribute could create as situation where you have divergence in translated content if you aren't careful.