Skip to content

New SPA Runtime Configuration and Language Selector #880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 31 commits into from
Nov 12, 2025
Merged

New SPA Runtime Configuration and Language Selector #880

merged 31 commits into from
Nov 12, 2025

Conversation

@g-saracca
Copy link
Contributor

@g-saracca g-saracca commented Oct 24, 2025 •
edited
Loading

What this PR does / why we need it:

This PR introduces two major improvements to the React SPA configuration and internationalization.

1. Runtime configuration

  • Replaced environment variables (.env) with a runtime configuration file located at public/config.js.
  • The configuration is now validated at runtime using a Zod schema to ensure correctness before the app initializes.
  • This allows building the application once and deploying it to different environments by simply updating the config.js file in the build output.

2. Language configuration and internationalization improvements

  • Extended the runtime configuration to include:
    • languages: the list of available languages
    • defaultLanguage: the fallback language when no match is found
  • Added a language switcher component that is only displayed when more than one language is configured.
  • Added Spanish translations and removed unused metadata block translations.
  • Improved language initialization logic with a clear order of precedence:
    • Language stored in localStorage
    • Browser language (if supported)
    • Default language from app configuration
  • Added automatic synchronization between the active language and the tag’s attributes (lang and dir).
    • Example: <html lang="en" dir="ltr"> or <html lang="ar" dir="rtl">
    • This lays the groundwork for future RTL language support.

Related to tests:

  • All component and end-to-end tests continue to pass.
  • Added example tests showing how to override runtime configuration for different scenarios.

Which issue(s) this PR closes:

Special notes for your reviewer:

You may want to remove the Spanish language for beta, demo or qa, to do that remove that option from the public/config.js languages property array and also remove it from the deploy actions config overrides.

Suggestions on how to test this:

Step 1: Run the Development Environment

  1. Execute npm i.
  2. Navigate with cd packages/design-system && npm i && npm run build.
  3. Return with cd ../../.
  4. Navigate with cd dev-env.
  5. Start the environment using ./run-env.sh unstable .
  6. To verify the environment, visit http://localhost:8000/ and check your local Dataverse installation.

Step 2:
Test the new runtime configuration.

  1. Open the SPA, everything should work the same.
  2. Modify the public/config.js file, for example remove the backendUrl line and reload the spa.
  3. You should see a config.js file related schema validation error (see screenshot below).
  4. Now revert that file as it was originally.
  5. Let's test the language functionality now. Navigate to the homepage and change the language, you should see translations according to the selected language.
  6. Now open the devTools -> Application tab -> Local Storage -> delete the DV_lang record.
  7. In Chrome for example, open Settings -> Languages -> Add Language Spanish and move it to the top.
  8. Reload the SPA, you should get the Spanish Language by default. Revert to English, reload the spa and you should get English Language.
  9. If you select Spanish Language on the SPA and your browser preferrred language setting is English the SPA will load in spanish since it was what you have selected in the SPA UI.

Does this PR introduce a user interface change? If mockups are available, please link/include them here:

Yes.

Language Switcher
Screenshot 2025-10-30 at 14 57 55

In case there is a config.js schema validation error when initializing the app.
Screenshot 2025-10-30 at 15 04 27

Is there a release notes or changelog update needed for this change?:

Added to the CHANGELOG.

Additional documentation:

@coveralls
Copy link

coveralls commented Oct 24, 2025 •
edited
Loading

Coverage Status

coverage: 97.746% (-0.08%) from 97.823%
when pulling 3d08dfd on 877-spa-runtime-config
into e1957ab on develop.

@g-saracca
feat: add defaultLanguage to app configuration and update tests
7a008d0
@g-saracca
chore: update dependencies for i18next and related packages
de7bbaa
@g-saracca
feat: add language switcher
8dba1cb
@g-saracca
feat: add spanish localization
2ad08db
@g-saracca
feat: update html tag lang and dir attributes
e90b23e
@g-saracca
feat: locales for testing language-region codes
2f99961
@g-saracca
fix: ensure language switcher is hidden when only one language is con…
c570337 
…figured
@g-saracca
fix: change locale
d905208
@g-saracca
fix: trans component usage
e3d560c
@g-saracca
remove region spanish
5697aab
@g-saracca
feat: apply test config in component tests before each test
662ed27
@g-saracca
test: test for language switcher
148bcae
@g-saracca
test: add clear comments about app config for components test
5990b3c
@g-saracca
fix: standardize environment variable names in tests
01b08a6
@g-saracca
refactor: remove spa .env file creation from test action
1c9f700
@g-saracca
refactor: remove VITE_DATAVERSE_BACKEND_URL environment variable from…
d28430b 
… dev_frontend service
@g-saracca
refactor: replace .env file creation with runtime config.js for envir…
82db868 
…onment variables
@g-saracca
fix: correct build and preview script options in package.json
afe627a
@g-saracca
revert: correct build and preview script options in package.json
8d002c7
@g-saracca
change push branchs to test deploy to beta workflow
2c45d2f
@g-saracca
fix: order, first build then override config.js
7daa332
@g-saracca
docs: add comments and some tweaks
1b59f50
@g-saracca
revert on push branchs
b23f0c1
@g-saracca
cleanups after reviewing PR
d41c02c
@g-saracca g-saracca moved this to Ready for Review ⏩ in IQSS Dataverse Project Oct 30, 2025
@g-saracca g-saracca added Size: 10 A percentage of a sprint. 7 hours. GREI Re-arch GREI re-architecture-related labels Oct 30, 2025
@g-saracca g-saracca marked this pull request as ready for review October 30, 2025 19:33
@g-saracca g-saracca changed the title 877 spa runtime config New SPA Runtime Configuration and Language Selector Oct 31, 2025
ekraffmiller
ekraffmiller approved these changes Oct 31, 2025
View reviewed changes
Copy link
Contributor

@ekraffmiller ekraffmiller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good! thanks for the update to the developer guides :)

@github-project-automation github-project-automation bot moved this from Ready for Review ⏩ to Ready for QA ⏩ in IQSS Dataverse Project Oct 31, 2025
@cmbz cmbz added FY26 Sprint 9 FY26 Sprint 9 (2025-10-22 - 2025-11-05) FY26 Sprint 10 FY26 Sprint 10 (2025-11-05 - 2025-11-19) labels Nov 5, 2025
@ChengShi-1 ChengShi-1 self-assigned this Nov 6, 2025
@ChengShi-1 ChengShi-1 moved this from Ready for QA ⏩ to QA ✅ in IQSS Dataverse Project Nov 7, 2025
@ChengShi-1 ChengShi-1 removed their assignment Nov 12, 2025
@ChengShi-1 ChengShi-1 merged commit d4ca076 into develop Nov 12, 2025
9 of 12 checks passed
@github-project-automation github-project-automation bot moved this from QA ✅ to Merged 🚀 in IQSS Dataverse Project Nov 12, 2025
@scolapasta scolapasta moved this from Merged 🚀 to Done 🧹 in IQSS Dataverse Project Nov 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ekraffmiller ekraffmiller ekraffmiller approved these changes

Assignees

No one assigned

Labels

FY26 Sprint 9 FY26 Sprint 9 (2025-10-22 - 2025-11-05) FY26 Sprint 10 FY26 Sprint 10 (2025-11-05 - 2025-11-19) GREI Re-arch GREI re-architecture-related Size: 10 A percentage of a sprint. 7 hours.

Projects

IQSS Dataverse Project
Status: Done 🧹

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

SPA runtime config PoC

6 participants

@g-saracca @coveralls @ekraffmiller @cmbz @ChengShi-1