Repository navigation
Localize Mapbox map labels to the user's preferred app locale - #99304
Conversation
Co-authored-by: Rory Abraham <roryabraham@users.noreply.github.com>
Codecov Report✅ Changes either increased or maintained existing code coverage, great job!
|
This comment was marked as low quality.
This comment was marked as low quality.
This comment was marked as low quality.
This comment was marked as low quality.
|
🚧 roryabraham has triggered a test Expensify/App build. You can view the workflow run here. |
This comment has been minimized.
This comment has been minimized.
|
@MelvinBot This doesn’t work on web, and it looks like the change only supports two languages. |
|
You're right on both counts. I reproduced the web failure and traced why. 1. "Doesn't work on web" — confirmed. I tested on web: switched the app to Japanese, and the map's place/road labels stayed entirely English while the rest of the UI localized. So the Root cause: In mapbox-gl v3, To confirm the last step, open the map on web and check Fix options (roughly increasing effort):
2. "Only supports two languages" — it's a bit different, but there is a real gap. I'm not pushing a fix here since the most likely real fix is a Mapbox Studio style change outside this repo, and I'd want Test result: fail — map labels did not localize on web after switching to Japanese.
Evidence (2)Distance map with app language English — all place/road labels in English
Same route after switching app language to Japanese — UI is Japanese but map labels remain English
|
|
@linhvovan29546 @MelvinBot I can confirm I see toggles to have language and worldview "Configured in SDK":
But I don't want to enable that without confirming first that we are configuring Mapbox language and worldview in the Expensify app in production. Do we need to merge and deploy this PR first, then enable those settings?
Regarding this: I understand it could be a larger refactor, but would switching to Google Maps provide more complete localization? I don't recall the context for why we used Mapbox in the first place, but I recall that it being closed-source comes with some extra config burden in this repo. Is there a ready-to-go Google Maps library for React Native? |
|
Short answer: No — production configures neither today. Deploy this PR first, then flip Language only. Do not flip Worldview. And no, we don't need Google Maps: I was wrong about the 3 missing locales. 1. Are we configuring language/worldview in production today?No, neither. 2. Ordering: deploy first, then flip LanguageDeploy first is the safe order. Merging is a no-op today: the style pins labels to English, so Flipping first is the risky order. The style is server-side, so it takes effect instantly for every client — current production, old native builds, cached web sessions. Those clients set no language, and Mapbox's documented default is the browser/device locale, not English. A user with a German browser and an English app would suddenly get German map labels, with no deploy to roll back through. Leave Worldview pinned. It controls disputed-boundary rendering, defaults to 3. Google Maps? No — and I owe you a correctionMy "el/nl/pl will never localize" claim was wrong. That was the old The real gap is native, not Mapbox. Web and native use different mechanisms:
So after the flip, web gets all 11 locales and native still misses 3. The fix is moving native to the same server-side path (Mapbox's Why Google Maps would cost far more than it returns
Verifying before you publish the styleStudio keeps a draft version of the style. If the token scope allows it, point a local build at Style URL is at Recommended sequence: merge + deploy → flip Language to "Configured in SDK" (leave Worldview) → verify on web with a locale like Greek or Polish, which only work through the server-side path → file a follow-up for native server-side language. Sources: Mapbox maps internationalization, Android localization plugin |
|
Ok:
|
|
@MelvinBot Please check #99304 (comment) |
Mapbox draws disputed borders from the perspective of the worldview it is given. The map never set one, so every user saw the style's default. Web now sends the worldview matching the user's country alongside the label language. Co-authored-by: Rory Abraham <roryabraham@users.noreply.github.com> Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
Co-authored-by: Rory Abraham <roryabraham@users.noreply.github.com>
|
Fixed the failing check — pushed
The other failing check, Verification
|
Mapbox falls back to the style's default worldview for country codes it has no worldview for, so an allowlist only adds a list that goes stale as Mapbox adds worldviews. Only values that aren't country codes at all still need dropping, since those raise an error. Co-authored-by: Rory Abraham <roryabraham@users.noreply.github.com> Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
…ude-mapboxMapLocale Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
|
Worldview is wired up on web and pushed ( 1. WorldviewWeb now sends worldview alongside language, from the user's country by IP:
Two things worth your call, The country source. Worldview is a country, not a language, so it can't come from This is a policy change, not just plumbing. Today every user sees the style's default worldview. After this, an Indian user sees Indian borders and a Chinese user sees Chinese borders. That's the point of the feature, but it's a decision about disputed territory, so flag it if you'd rather pin it. I pass any well-formed country code straight through rather than allowlisting Heads-up:
|
|
MelvinBot has made 5 consecutive commits trying to fix CI failures. Automatic CI fix dispatches are now paused for this PR. Next steps: A human should review the recent commits and resolve the conflicting CI errors manually. |
|
@MelvinBot Please merege main and resolve conflicts |
Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com> # Conflicts: # src/components/MapView/MapViewImpl.web.tsx
|
I merged The only conflict was in
The localization effect depends on Checks
|
|
@MelvinBot Please mark the PR ready for review! |
|
Yes, I'd keep QA, but only as a short regression check. Don't mark this Labels won't change on web until the Mapbox Studio style is updated. The new code still runs in production, though. On web,
Checking that labels follow the app language belongs after the Studio change. An Expensify engineer with Mapbox access would make the change and check it on web. Native is different. It switches labels on the device, so it shouldn't depend on the Studio setting. That hasn't been confirmed visually. What changed in the PR description
|
Reviewer Checklist
Screenshots/Videos |
Issue 1 —
|
…eject Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
|
Issue 1 is fixed in 3b0f983. Issue 2 isn't a bug in this PR. Mapbox has no German, Spanish, French, Italian, or Portuguese names for most San Francisco streets. Issue 1:
|
| Step | Status |
|---|---|
| ✅ | |
| ✅ | |
| ✅ |
Ok, I see that |
|
@MelvinBot Please update the test steps in the PR to specify which languages can be tested in Mapbox. |
|
I updated the Tests section in the PR description to list which languages you can test on each platform.
The steps now test Japanese first, because it changes the most labels in San Francisco. For the other languages, the steps say to zoom out and check country and city names, because most San Francisco street names have no translation. |
linhvovan29546
left a comment
There was a problem hiding this comment.
Issue 1: nl, pl, el errors
The native Mapbox SDKs (11.23.1, the version @rnmapbox/maps 10.3.2 pins) only localize labels to a fixed list of languages: ar, en, es, fr, de, it, pt, ru, ja, ko, vi, zh-Hans, zh-Hant. Dutch, Polish, and Greek aren't on that list. iOS throws an error for them, and Android logs a warning and skips them.
For these languages, Mapbox uses the old API, which doesn’t support them. We need to update rnmapbox to support these languages, and this should be handled in a separate PR.
trjExpensify
left a comment
There was a problem hiding this comment.
This PR has no visible effect until the Mapbox Studio style is updated
Might want to [NO QA] it then?
Some languages have a visible effect on the native side, so we still need QA testing. |
|
@MelvinBot Please merge the main branch |
Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
I opened an upstream PR to add support for these languages: rnmapbox/maps#4327. The maintainer (thanks to |
|
@MelvinBot Please merge the main branch |
|
@roryabraham Could you please take a look at this PR when you have a chance? Thanks! |
Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
|
✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release. |
|
🚧 roryabraham has triggered a test Expensify/App build. You can view the workflow run here. |
|
🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
|
|
🚀 Deployed to staging by https://github.com/roryabraham in version: 9.5.15-1 🚀
|
|
No help site update is needed. Map labels now follow the language you already set, which matches what users expect, and no sentence in |
|
🚀 Deployed to production by https://github.com/grgia in version: 9.5.15-3 🚀
Bundle Size Analysis (Sentry): |














Explanation of Change
The Mapbox map never told Mapbox which language or worldview to use. Map labels (place and road names) stayed in English and ignored the app language. This PR sends the user's language and worldview to Mapbox:
MapViewImpl.web.tsx): once the style loads, callsmapbox-gl'smap.setLanguage(...)with the user'spreferredLocaleandmap.setWorldview(...)with the user's country (ONYXKEYS.COUNTRY, the country by IP). It runs again when the map, locale, or country changes.MapView.tsx): passeslocalizeLabels={{locale}}to<Mapbox.MapView>.utils.ts):getMapboxLanguagemaps app locales to Mapbox language codes. Onlypt-BR→ptandzh-hans→zh-Hansneed remapping. The other locales pass through unchanged.getMapboxWorldviewpasses any two-letter country code through. Mapbox uses the style's default worldview for countries it has no worldview for. Anything that isn't a two-letter code is dropped, because Mapbox throws on codes it can't parse.Unit tests were added for both helpers.
This PR has no visible effect until the Mapbox Studio style is updated
Our Mapbox Studio style (
mapbox://styles/expensify/cllcoiqds00cs01r80kp34tmq) fixes labels to English. Until someone sets Language to "Configured in SDK" in Mapbox Studio, labels stay in English on web, even with this PR deployed. Native switches labels on the device, so it doesn't depend on this setting, but that hasn't been confirmed visually.Deploy this PR before changing the style. The style change is server-side, so it applies to every client at once. Clients that don't send a language fall back to the browser or device locale, not English. Deploying first means every client already sends the app language when the style changes.
Rollout order:
Known limitations on native
@rnmapbox/mapsv10.3.2 only localizes labels on the device, by switching labels to thename_{code}fields in the map data. Those fields cover about 12 languages, so native won't localize Greek, Dutch, or Polish. The library also has no worldview support. Web uses Mapbox's server-side path, which covers all 11 app locales.Fixing this needs an upstream change to
@rnmapbox/mapsto expose the native SDK's server-sidelanguageandworldviewsettings (MapboxMapsOptions). That is a follow-up and is out of scope for this PR. A draft for the rnmapbox Ideas discussion board is in this comment.Fixed Issues
$ #97752
PROPOSAL: #97752 (comment)
Tests
Which languages can be tested depends on the platform. Set the language in Settings → Preferences → Language.
Not every label changes. Mapbox only translates a label when it has a name in that language. In San Francisco, most street names have no translation, so they stay in English. Japanese and Chinese show the most changes in San Francisco, for example landmark names. For the other languages, check country and city names by zooming out or by using a city outside the US.
Offline tests
N/A. The map isn't shown offline.
QA Steps
Same as tests. This is a regression check only. On web, map labels are expected to stay in English until the Mapbox Studio style is updated.
PR Author Checklist
### Fixed Issuessection aboveTestssectionOffline stepssectionQA stepssectionAvatar, I verified the components usingAvatarare working as expected)StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))npm run compress-svg)Avataris modified, I verified thatAvataris working as expected in all cases)Designlabel and/or tagged@Expensify/designso the design team can review the changes.mainbranch was merged into this PR after a review, I tested again and verified the outcome was still expected according to theTeststeps.Screenshots/Videos
Android: Native
Android: mWeb Chrome
iOS: Native
iOS: mWeb Safari
MacOS: Chrome / Safari