Skip to content

feat: localize widget labels and initial states#143

Merged
V3RON merged 7 commits intomainfrom
feature/localization-support-widget-preview
May 5, 2026
Merged

feat: localize widget labels and initial states#143
V3RON merged 7 commits intomainfrom
feature/localization-support-widget-preview

Conversation

@V3RON
Copy link
Copy Markdown
Contributor

@V3RON V3RON commented May 4, 2026

This PR adds first-class localization support for Voltra home screen widgets, so app developers can ship widget names, descriptions, and pre-rendered initial states in multiple languages without maintaining separate native localization code by hand.

What this means for Voltra users

  • you can now provide localized displayName and description values in the Expo plugin config using locale maps instead of a single string
  • you can localize initialStatePath, so the widget’s first rendered state can match the user’s language before the app updates it
  • iOS and Android now pick the best localized value automatically from the device locale, with fallback behavior that matches user expectations
  • Android supports script-based locale tags such as zh-Hans, so widget picker strings can be packaged correctly for those locales too

User-facing behavior

  • Voltra first tries an exact locale match
  • if there is no exact match, it falls back to a language-only match
  • if there is still no match, it prefers an English locale such as en or en-US
  • if no English locale exists, it uses the first configured locale

Included in this PR

  • Expo plugin support for localized widget labels and descriptions on iOS and Android
  • localized pre-rendered widget initial states
  • native iOS and Android locale selection helpers
  • validation and tests for locale keys and fallback behavior
  • example config updates and docs describing how to configure localization

Testing

  • npm test --workspace @use-voltra/expo-plugin
  • npm run lint --workspace @use-voltra/expo-plugin
  • npm run build --workspace @use-voltra/expo-plugin

pasyukevich and others added 6 commits April 30, 2026 19:35
- Allow initialStatePath as a string or per-locale path map; validate with existing locale key rules
- Prerender one JSON payload per locale; iOS bundles locale map + VoltraInitialStateLocale picker; Android uses __voltraLocales in voltra_initial_states.json with VoltraWidgetManager resolution
- Add localePick.ts for shared fallback order (matches Swift/Kotlin)
- Replace hardcoded English placeholders with ProgressView / ProgressBar
- Document locale maps in website docs, plugin schema, and example app.json
- Add Jest in expo-plugin (ts-jest) and unit tests; exclude *.node.test.ts from tsc build

Co-authored-by: Cursor <cursoragent@cursor.com>
@V3RON V3RON changed the title Feature/localization support widget preview feat(expo-plugin): localize widget labels and initial states May 5, 2026
@V3RON V3RON changed the title feat(expo-plugin): localize widget labels and initial states feat: localize widget labels and initial states May 5, 2026
@V3RON V3RON merged commit dbcd3b0 into main May 5, 2026
12 checks passed
@V3RON V3RON deleted the feature/localization-support-widget-preview branch May 5, 2026 10:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants