Skip to content

Localize Mapbox map labels to the user's preferred app locale - #99304

Merged
roryabraham merged 10 commits into
mainfrom
claude-mapboxMapLocale
Oct 20, 2026
Merged

roryabraham merged 10 commits into
mainfrom
claude-mapboxMapLocale

Conversation

@MelvinBot

@MelvinBot MelvinBot commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

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:

  • Web (MapViewImpl.web.tsx): once the style loads, calls mapbox-gl's map.setLanguage(...) with the user's preferredLocale and map.setWorldview(...) with the user's country (ONYXKEYS.COUNTRY, the country by IP). It runs again when the map, locale, or country changes.
  • Native (MapView.tsx): passes localizeLabels={{locale}} to <Mapbox.MapView>.
  • Helpers (utils.ts):
    • getMapboxLanguage maps app locales to Mapbox language codes. Only pt-BR → pt and zh-hans → zh-Hans need remapping. The other locales pass through unchanged.
    • getMapboxWorldview passes 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:

  1. Merge and deploy this PR. No visible change is expected.
  2. An Expensify engineer with Mapbox Studio access sets Language to "Configured in SDK" and publishes the style.
  3. Decide separately whether to set Worldview to "Configured in SDK". It changes how disputed borders are drawn, so it's a policy decision. Native doesn't send a worldview (see the next section).
  4. Verify on web that map labels follow the app language. Greek or Polish are good checks, because only the web path supports them.

Known limitations on native

@rnmapbox/maps v10.3.2 only localizes labels on the device, by switching labels to the name_{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/maps to expose the native SDK's server-side language and worldview settings (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.

Note: setLanguage and setWorldview are marked @private in mapbox-gl 3.24. They're typed and work, but they could change without a major version bump.

Fixed Issues

$ #97752
PROPOSAL: #97752 (comment)

Tests

Which languages can be tested depends on the platform. Set the language in Settings → Preferences → Language.

App language Web iOS / Android native
English, Spanish, French, German, Italian, Portuguese (BR), Japanese, Chinese (Simplified) Localized after the Mapbox Studio change. English until then. Localized
Dutch, Polish, Greek Localized after the Mapbox Studio change. English until then. Not localized. Labels stay in the style's default language, with no error.

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.

  1. Go to FAB → Create expense → Distance.
  2. Add a start and a stop.
  3. Verify the map loads, shows both markers, and draws the route.
  4. Go to Settings → Preferences → Language and select Japanese.
  5. Return to the Distance map.
  6. Verify the map still loads, shows both markers, and draws the route.
  7. On native, verify some labels are in Japanese, for example landmark names. On web, labels stay in English until the Mapbox Studio style is updated.
  8. Zoom out until country and city names show.
  9. Repeat steps 4–8 with Spanish, French, German, Italian, Portuguese (BR), and Chinese (Simplified). On native, verify some country or city names are in the selected language.
  10. Repeat steps 4–6 with Dutch, Polish, and Greek. On native, verify labels stay in the default language and no Mapbox "is currently not supported" error appears. On iOS this shows as a RedBox in dev builds. On Android, check Logcat.
  11. Switch the language back to English and repeat step 6.
  • Verify that no errors appear in the JS console

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.

  • Verify that no errors appear in the JS console

PR Author Checklist

  • I linked the correct issue in the ### Fixed Issues section above
  • I wrote clear testing steps that cover the changes made in this PR
    • I added steps for local testing in the Tests section
    • I added steps for the expected offline behavior in the Offline steps section
    • I added steps for Staging and/or Production testing in the QA steps section
    • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
    • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
    • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
  • I included screenshots or videos for tests on all platforms
  • I ran the tests on all platforms & verified they passed on:
    • Android: Native
    • Android: mWeb Chrome
    • iOS: Native
    • iOS: mWeb Safari
    • MacOS: Chrome / Safari
  • I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
  • I followed proper code patterns (see Reviewing the code)
    • I verified that comments were added to code that is not self explanatory
    • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
    • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
  • If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
  • I followed the guidelines as stated in the Review Guidelines
  • I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
  • If a new CSS style is added I verified that:
    • A similar style doesn't already exist
    • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
  • If new assets were added or existing ones were modified, I verified that:
    • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
    • The assets load correctly across all supported platforms.
  • If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
  • If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
  • If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
  • If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
  • If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
    • I verified that all the inputs inside a form are aligned with each other.
    • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
  • I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
  • If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native
Android: mWeb Chrome
iOS: Native
iOS: mWeb Safari
MacOS: Chrome / Safari

Co-authored-by: Rory Abraham <roryabraham@users.noreply.github.com>
@codecov

codecov Bot commented Aug 24, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines Coverage Δ
src/components/MapView/MapView.tsx 56.86% <100.00%> (+0.86%) ⬆️
src/components/MapView/utils.ts 92.96% <100.00%> (+0.86%) ⬆️
src/components/MapView/MapViewImpl.web.tsx 0.00% <0.00%> (ø)
... and 11 files with indirect coverage changes

@MelvinBot

This comment was marked as low quality.

@MelvinBot

This comment was marked as low quality.

@github-actions

Copy link
Copy Markdown
Contributor

🚧 roryabraham has triggered a test Expensify/App build. You can view the workflow run here.

@github-actions

This comment has been minimized.

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot This doesn’t work on web, and it looks like the change only supports two languages.
https://github.com/Expensify/App/pull/99304/changes#diff-a7f8ac7902cdbf14643da46189b14ee847a5169165fbf0f8fbfb9248fb96f62dR6

@MelvinBot

Copy link
Copy Markdown
Contributor Author

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 setLanguage() wiring runs but has no visible effect.

Root cause: In mapbox-gl v3, map.setLanguage() does not rewrite any layer's text-field. All it does is reload the vector sources with a language= query param and let Mapbox's tile server localize the generic name field. That only shows up if the style's symbol layers actually render {name}. Our classic Studio style (mapbox://styles/expensify/cllcoiqds00cs01r80kp34tmq) was authored in Mapbox Studio, which bakes the label language in at authoring time — its symbol layers almost certainly pin text-field to {name_en}, so the server-side localization is ignored and labels stay English. The code path is correct; the style is the blocker.

To confirm the last step, open the map on web and check map.getStyle().layers (the symbol layers' layout['text-field']) — if it reads name_en, that's it.

Fix options (roughly increasing effort):

  • Edit the Mapbox Studio style so label layers use {name} instead of {name_en}. This is a change in the Expensify Mapbox account, not in this repo — needs whoever owns it. This is the smallest fix and makes the current code work as-is.
  • Migrate the map to the newer Mapbox Standard style, which exposes a first-class language config that drives labels dynamically.
  • Rewrite the symbol layers' text-field in code after style load (what the old @mapbox/mapbox-gl-language plugin did) — brittle, least preferred.

2. "Only supports two languages" — it's a bit different, but there is a real gap. getMapboxLanguage only remaps two locales (pt-BR→pt, zh-hans→zh-Hans); the other 9 pass through unchanged because they're already valid codes — that part is fine. The real limitation is that Mapbox Streets' classic tileset only has name_* translations for a subset (ar, en, es, fr, de, it, ja, ko, pt, ru, vi, zh-Hans, zh-Hant). So of our 11 app locales, el (Greek), nl (Dutch), and pl (Polish) will never localize even after the style is fixed — they pass through and silently fall back to each label's local name. Worth calling out in the PR notes so it's not mistaken for a bug later.

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 roryabraham to weigh in on which of the three approaches to take.

Test result: fail — map labels did not localize on web after switching to Japanese.

Step Status Observation
Baseline: Distance map (NY→Boston) labels in English while app is English ✅ pass Labels render in English (Massachusetts, Connecticut, Hartford, etc.)
Switch app language to 日本語 (Japanese) ✅ pass All app UI chrome switched to Japanese immediately
Re-open Distance map — expect Japanese map labels ❌ fail UI is Japanese but map labels are the identical English strings — no Japanese anywhere on the tiles
Console/network for mapbox errors on map screen ✅ pass No 4xx/5xx to api.mapbox.com; no error banners (direct JS console not queryable on web harness)
Evidence (2)

Distance map with app language English — all place/road labels in English

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

Same route after switching app language to Japanese — UI is Japanese but map labels remain English

view run

@roryabraham

Copy link
Copy Markdown
Contributor

@linhvovan29546 @MelvinBot I can confirm I see toggles to have language and worldview "Configured in SDK":

Image

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?

The real limitation is that Mapbox Streets' classic tileset only has name_* translations for a subset (ar, en, es, fr, de, it, ja, ko, pt, ru, vi, zh-Hans, zh-Hant). So of our 11 app locales, el (Greek), nl (Dutch), and pl (Polish) will never localize even after the style is fixed

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?

@MelvinBot

Copy link
Copy Markdown
Contributor Author

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. origin/main has zero references to setLanguage, localizeLabels, setWorldview, or worldview anywhere in src/. This PR adds language only — it never sets worldview on either platform.

2. Ordering: deploy first, then flip Language

Deploy first is the safe order. Merging is a no-op today: the style pins labels to English, so setLanguage() has no visible effect — that's exactly what linhvovan29546 hit. Nothing regresses in the gap.

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 US, and this PR never sets it. Flipping it hands border rendering to device locale — a policy call unrelated to this PR.

3. Google Maps? No — and I owe you a correction

My "el/nl/pl will never localize" claim was wrong. That was the old streets-v8 name_* field list. Mapbox now supports 40+ label languages server-side, and all 11 of our locales are covered — including el, nl, and pl. Google's ~74 languages is a longer list, but it covers nothing extra that we actually ship.

The real gap is native, not Mapbox. Web and native use different mechanisms:

Mechanism Languages Needs the Studio toggle?
Web map.setLanguage() — server-side tile request 40+, incl. el/nl/pl Yes
Native localizeLabels — client-side name_{code} rewrite ~12 tile fields, no el/nl/pl No

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 SettingsService LANGUAGE key) — but @rnmapbox/maps v10.3.2 doesn't expose it, so that needs a small native module or an upstream PR. Worth a follow-up issue, not a provider swap.

Why Google Maps would cost far more than it returns
  • Routing is server-side and Mapbox-based. getRoute calls the GetRoute API command; the backend computes the route and distance. Swapping the display map doesn't swap routing, and Google's ToS restricts rendering third-party routing data on a Google map — so you'd likely have to migrate distance calculation too, which changes billed mileage. That's a much bigger blast radius than a UI swap.
  • No single library covers our platforms. react-native-maps handles iOS/Android but has no first-party web support; web would need @vis.gl/react-google-maps. You'd own two map implementations instead of one.
  • The config burden doesn't go away. Google needs platform-restricted API keys per platform, same as the Mapbox token setup.
  • Pricing. Google Maps Platform bills per map load and is generally more expensive than Mapbox at scale.
  • We already use Google Places for address autocomplete (AddressSearch), so the account exists — that lowers setup cost only, not migration cost.
Verifying before you publish the style

Studio keeps a draft version of the style. If the token scope allows it, point a local build at mapbox://styles/expensify/cllcoiqds00cs01r80kp34tmq/draft and confirm labels follow app locale before publishing. Caveat I couldn't verify: our Mapbox token comes from the backend via GetMapboxAccessToken and probably lacks the styles:draft scope, so this may need a temporary dev token.

Style URL is at src/CONST/index.ts:6402. PR wiring: MapViewImpl.web.tsx:201-221 (web), MapView.tsx:264-275 (native), utils.ts:5-21 (locale mapping — pt-BR→pt and zh-hans→zh-Hans are the only remaps needed, and both are valid Mapbox codes).

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


view run

@roryabraham

Copy link
Copy Markdown
Contributor

Ok:

  • I think we should update this PR to set worldview in addition to language (might as well?)
  • Can we find or create an upstream issue for the https://github.com/rnmapbox/maps limitation Melvin is referencing, then fix it with an upstream PR and patch?

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please check #99304 (comment)

MelvinBot and others added 2 commits September 4, 2026 03:27
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>
@MelvinBot

Copy link
Copy Markdown
Contributor Author

Fixed the failing check — pushed e73ea1d3.

Oxfmt check was the only real failure. oxfmt wants a blank line between the @src/... and relative import groups in src/components/MapView/utils.ts:3. Running npm run fmt added it; that's the entire diff (1 line).

The other failing check, Check independent approval, just needs a human reviewer — nothing to fix in code.

Verification
  • npm run fmt is now idempotent and reports no diff.
  • npx eslint src/components/MapView/utils.ts → clean.
  • npm test tests/unit/MapViewUtilsTest.ts → 23/23 passed.
  • Local oxfmt pin (^0.55.0) matches main, so the local run reproduces CI.
  • Skipped typecheck locally (tsgo isn't installed in this environment); it passed on CI for this exact code, and a blank line can't affect it.

view run

MelvinBot and others added 2 commits September 4, 2026 03:33
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>
@MelvinBot

Copy link
Copy Markdown
Contributor Author

Worldview is wired up on web and pushed (611f1a4). The upstream ask is half done: I searched, there's no existing report, and I drafted one — but my token can't post to third-party repos, so someone needs to paste it. Details below.


1. Worldview

Web now sends worldview alongside language, from the user's country by IP:

Two things worth your call, roryabraham:

The country source. Worldview is a country, not a language, so it can't come from preferredLocale. I used ONYXKEYS.COUNTRY (country by IP) — already loaded app-wide, no extra request, and it matches "where the user is", which is what worldview is for. The alternative is their address country from PRIVATE_PERSONAL_DETAILS, which is more deliberate but often unset. Easy to swap.

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 US/CN/IN/JP. Mapbox's own docs say unsupported ISO codes fall back to the TileJSON default and only invalid codes error, so an allowlist would just go stale as Mapbox adds worldviews.

Heads-up: setLanguage and setWorldview are marked @private in mapbox-gl 3.24

Both are exported in the type definitions, so TypeScript is happy and they work — but mapbox-gl-dev.js annotates both with @private. They aren't part of the public API surface and could change without a major bump. This applies to the setLanguage call that was already in this PR too. Worth knowing before we depend on them.

Native gets no worldview. @rnmapbox/maps has zero worldview support — the string doesn't appear anywhere in its src/, android/ or ios/. So after this, web honors worldview and native doesn't. That's the same gap as the upstream item below.

2. Upstream

Found: nothing tracking this. Closest matches are rnmapbox/maps#4172 (someone hitting the identical wall in March, still unanswered) and issues #1325 / #3302 / #284 / #740, all closed and all about bugs in the client-side path rather than the missing server-side one.

Venue: not an issue. rnmapbox sets blank_issues_enabled: false and their only template is a bug report; their config routes feature requests to Discussions → Ideas. A feature request filed as an issue gets auto-closed by their label bot as "rather a question than an issue" — that's literally what happened on #897.

Blocked: createDiscussion returns FORBIDDEN — Resource not accessible by personal access token. My token is scoped to Expensify repos, so I can't post it. The draft is ready to paste as-is into Ideas:

Ready-to-post draft — title + body

Title: Expose server-side language and worldview (MapboxMapsOptions) in addition to localizeLabels


Summary

@rnmapbox/maps can localize map labels only through the client-side localization extension (localizeLabels). It has no binding for the server-side language and worldview settings that the Mapbox Maps SDK v11 exposes via MapboxMapsOptions. That leaves two gaps that can't be worked around from JS:

  1. Languages. localizeLabels rewrites each symbol layer's text-field to name_{code}, so it only reaches the ~12 languages that exist as name_* fields in the Mapbox Streets tiles. The server-side path covers 40+ languages. Greek, Dutch and Polish are examples that work server-side and cannot work client-side.
  2. Worldview. There is no worldview support at all — worldview does not appear anywhere in src/, android/ or ios/. Apps can't choose how disputed borders are drawn.

Both are already available on the native SDK version this library pins (11.23.1, and the API landed in v11.8.0), and both are already available on web through mapbox-gl's map.setLanguage() / map.setWorldview() — so today the same app localizes differently on web and on native.

Where it stands today

localizeLabels bottoms out in the localization extension on both platforms:

  • Android — android/src/main/java/com/rnmapbox/rnmbx/components/mapview/RNMBXMapView.kt: savedStyle?.localizeLabels(locale, mLocaleLayerIds) (from com.mapbox.maps.extension.localization.localizeLabels)
  • iOS — ios/RNMBX/RNMBXMapView.swift: try self.mapboxMap.style.localizeLabels(into: locale.locale, forLayerIds: locale.layerIds)

A search for MapboxMapsOptions across the repo returns nothing, so there's no existing path to the server-side setting.

Proposed API

These are process-wide settings on the Mapbox SDK rather than per-map properties, so they fit the existing static Mapbox.* module alongside setWellKnownTileServer / setTelemetryEnabled rather than becoming MapView props:

Mapbox.setLanguage('el');   // BCP-47; null/undefined resets to the SDK default
Mapbox.setWorldview('IN');  // ISO 3166-1 alpha-2; null/undefined resets to the style default

Sketch of the change:

  • src/specs/NativeMapboxModule.ts — add setLanguage(language: string | null): void; and setWorldview(worldview: string | null): void;
  • src/RNMBXModule.ts, src/Mapbox.ts / src/Mapbox.native.ts — re-export both
  • Android android/src/main/java/com/rnmapbox/rnmbx/modules/RNMBXModule.kt — @ReactMethod wrappers assigning com.mapbox.maps.MapboxMapsOptions.language / .worldview
  • iOS ios/RNMBX/RNMBXModule.swift + RNMBXModule.m — @objc wrappers assigning MapboxMapsOptions.language / .worldview

localizeLabels would keep working exactly as it does now; this is purely additive.

Related, but not the same thing

Context

Raised from #99304, where we're localizing map labels to the user's app language. Web gets every language we ship plus worldview; native is capped at what the tiles carry. Happy to put up a PR if maintainers are open to the API shape above.

Versions: @rnmapbox/maps 10.3.2, Mapbox Maps SDK 11.23.1 (iOS + Android).

3. Upstream PR + patch — not in this PR

The change set is the four bullets in the draft above, and it's small. But it's Kotlin and Swift, and I can't compile either here — this runner has no macOS for the iOS half and no working Android native build for the Kotlin half. Shipping a patch-package patch for native code that has never once been compiled would risk breaking the Android and iOS builds for a feature that is dormant until you flip the Studio toggle anyway.

My recommendation: land this PR and the Studio Language flip first (that's the whole win on web, and most of it on native), then do the upstream PR + patch as a follow-up on a machine that can build both platforms. It buys native el/nl/pl plus native worldview — real, but bounded, and not worth blocking the rest on.

Testing

Unit tests, lint, typecheck and cspell all pass — getMapboxWorldview has coverage for supported codes, unsupported-but-valid codes, and malformed input (23/23 in MapViewUtilsTest.ts). The 668 typecheck errors in this environment are all pre-existing and confined to four files under scripts/ and tests/unit/TSCompilerUtilsTest.ts; none are in MapView.

I could not verify at runtime. The web test session went blank after the branch checkout — 0 DOM nodes, blank screenshots — and recovering it needs a CI-owned session restart the test agent isn't allowed to perform. The dev server itself compiled both changed files cleanly, so this looks like test infra rather than the change, but treat the browser behavior as unverified. Since the Studio toggle isn't flipped yet, there's nothing visible to confirm regardless; what's worth re-checking once a session is healthy is simply that the map still draws and the console stays clean.


view run

@MelvinBot

Copy link
Copy Markdown
Contributor Author

⚠️ MelvinBot CI Fix Loop Detected

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.

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please merege main and resolve conflicts

Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>

# Conflicts:
#	src/components/MapView/MapViewImpl.web.tsx
@MelvinBot

Copy link
Copy Markdown
Contributor Author

I merged main into this branch and resolved the conflict. The merge commit is d35f1f5.

The only conflict was in src/components/MapView/MapViewImpl.web.tsx. Both sides added a new useEffect in the same place, so I kept both:

  • This PR's effect, which sets the map language and worldview
  • The ResizeObserver effect from main, which mounts the map only while its container has a real size

The localization effect depends on mapRef, so it runs again each time the map remounts.

Checks
  • ESLint: the only error is react-hooks/set-state-in-effect at MapView.tsx:196. That error already exists on main and this PR doesn't touch that line.
  • Typecheck: none of the errors are in MapView files. They come from the sandbox's out-of-date node_modules.
  • Jest: the test suite couldn't start in the sandbox for the same reason. CI will run the tests.

view run

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please mark the PR ready for review!

@MelvinBot
MelvinBot marked this pull request as ready for review October 9, 2026 06:52
@MelvinBot
MelvinBot requested a review from a team as a code owner October 9, 2026 06:52
@MelvinBot

Copy link
Copy Markdown
Contributor Author

Yes, I'd keep QA, but only as a short regression check. Don't mark this [No QA]. I updated the PR description to match.

Labels won't change on web until the Mapbox Studio style is updated. The new code still runs in production, though. On web, setLanguage and setWorldview make Mapbox reload the map data. QA should confirm these still work:

  • The Distance map loads, shows its markers, and draws the route.
  • Switching the app language doesn't break the map.
  • No errors appear in the JS console.

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
  • Explanation of Change: now covers worldview, both helpers, and why the PR has no visible effect on web until Language is set to "Configured in SDK" in Mapbox Studio.
  • Rollout order: deploy first, then change the Studio setting. Changing the style first would switch labels to the browser or device language for clients that don't send one yet.
  • Worldview: whether to set it to "Configured in SDK" is a separate policy decision, and native doesn't send a worldview.
  • Known limitations on native: no Greek, Dutch, or Polish labels and no worldview, with a link to the draft for an upstream @rnmapbox/maps change.
  • Tests and QA Steps: regression steps that match what can be seen today.

view run

@linhvovan29546

linhvovan29546 commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer Checklist

  • I have verified the author checklist is complete (all boxes are checked off).
  • I verified the correct issue is linked in the ### Fixed Issues section above
  • I verified testing steps are clear and they cover the changes made in this PR
    • I verified the steps for local testing are in the Tests section
    • I verified the steps for Staging and/or Production testing are in the QA steps section
    • I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
    • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I checked that screenshots or videos are included for tests on all platforms
  • I included screenshots or videos for tests on all platforms
  • I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
  • I verified tests pass on all platforms & I tested again on:
    • Android: HybridApp
    • Android: mWeb Chrome
    • iOS: HybridApp
    • iOS: mWeb Safari
    • MacOS: Chrome / Safari
  • If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
  • I verified any copy / text that was added to the app is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
  • If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
  • I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
  • If a new component is created I verified that:
    • A similar component doesn't exist in the codebase
    • All props are defined accurately
    • The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
    • The only data being stored in the state is data necessary for rendering and nothing else
    • The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
  • If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
  • If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
  • If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
  • If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
  • If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
    • I verified that all the inputs inside a form are aligned with each other.
    • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
  • If the PR adds or modifies the UI:
    • I asked an AI agent to review the changes for accessibility issues and addressed its findings.
    • I tested with a screen reader (VoiceOver on macOS) and verified all new/changed elements are reachable with a logical focus order.
    • I verified all new/changed elements have meaningful accessible names and roles.
    • I verified state changes are announced (e.g. checked/unchecked, expanded/collapsed, selected).
  • For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
  • If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
  • I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp Screenshot_1791543696 Screenshot_1791537244
Android: mWeb Chrome Screenshot_1791543221
iOS: HybridApp Screenshot_1791537244 Simulator Screenshot - iPhone 16 Pro Max - 2026-10-09 at 17 50 12 Simulator Screenshot - iPhone 16 Pro Max - 2026-10-09 at 15 23 34
iOS: mWeb Safari Simulator Screenshot - iPhone 16 Pro Max - 2026-10-09 at 17 53 07
MacOS: Chrome / Safari Screenshot 2026-10-09 at 17 51 32

@linhvovan29546

Copy link
Copy Markdown
Contributor

Issue 1 — nl/pl/el throw a native Mapbox error on every map load, both platforms

@MelvinBot Did manual verification of native label localization across all 11 app locales on iOS Simulator and Android Emulator (this branch, Track Distance map screen). Found something worth a look: nl, pl, and el aren't just missing translation — the native Mapbox Maps SDK rejects these three locale codes outright on every map load, on both platforms.

iOS (visible RedBox error in dev builds):

Mapbox [error] RNMBXMapView.applyLocalizeLabels()
MapError: Locale: nl (fixed nl) is currently not supported

(same error pattern individually confirmed for pl and el)

Android (same underlying error, logged as a Logcat warning, not visible in the UI):

W Mapbox : [maps-android\LocalizationPluginImpl]: Locale: nl is not supported.
W Mapbox : [maps-android\LocalizationPluginImpl]: Locale: pl is not supported.
W Mapbox : [maps-android\LocalizationPluginImpl]: Locale: el is not supported.

So any Dutch, Polish, or Greek user opening a native map screen gets this error logged every time. Can you dig into this?

Issue 2 — translated labels rarely show up even for locales that don't error

@MelvinBot Separately, tested de, es, fr, it, pt-BR, ja, zh-Hans at the same SF location (Track Distance map). Only ja (a single landmark) and zh-Hans (several streets/landmarks) showed any translated text. de/es/fr/it/pt-BR rendered 100% English labels — no visible difference from the default locale at all. Can you take a look at why coverage is this inconsistent across locales that are otherwise working without errors? Happy to share screenshots per locale if useful.

…eject

Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
@MelvinBot

MelvinBot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author

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: 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.

The fix adds getNativeMapboxLanguage, which returns undefined for languages that aren't on the list. MapView.tsx:266 then leaves out localizeLabels. Dutch, Polish, and Greek users see the style's default labels, with no error. Web is unchanged. Two unit tests were added, and all 28 tests pass.

Issue 2: few translated labels

This is how Mapbox's data works. Localization changes each label to name_<lang>, falling back to name. For most San Francisco streets, Mapbox Streets v8 has no name_de, name_es, name_fr, name_it, or name_pt. Those labels fall back to name, which is English. Japanese and Chinese have translations for more landmarks and some streets, so a few labels change. The same languages should show visible changes on country, city, and well-known place labels, for example in a city outside the US or at a zoomed-out view.

Sources

🤖 Android test steps verification results: ✅ pass

With Dutch, the Distance map loaded and logcat had no "is not supported" warning. With Japanese, the map loaded with some Japanese labels and no warning.
Language reset to English

Step Status
Dutch: Distance map loads, logcat has no "Locale: nl is not supported"The map loaded with default (English) labels. Logcat from the language change through the end of the Mapbox startup had no "is not supported" line.
Track Distance map in Dutch
✅
Japanese: Distance map loads, no "is not supported" warningThe map loaded with some Japanese labels, for example トランスアメリカ・ピラミッド. Logcat had no "is not supported" line.
Track Distance map in Japanese
✅
Language set back to EnglishPreferences > Language shows English.
Language reset to English
✅

view run · view recording

@linhvovan29546

Copy link
Copy Markdown
Contributor

Dutch, Polish, and Greek aren't on that list. iOS throws an error for them, and Android logs a warning and skips them.

Ok, I see that Mapbox already supports this: https://docs.mapbox.com/help/dive-deeper/maps-internationalization/. However, rnmapbox/maps uses the old API, which doesn’t include this support, so we need to fix it in rnmapbox/maps.

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please update the test steps in the PR to specify which languages can be tested in Mapbox.

@MelvinBot

Copy link
Copy Markdown
Contributor Author

I updated the Tests section in the PR description to list which languages you can test on each platform.

  • Native (iOS and Android): English, Spanish, French, German, Italian, Portuguese (BR), Japanese, and Chinese (Simplified) show localized labels. Dutch, Polish, and Greek keep the default labels and should show no "is currently not supported" error.
  • Web: labels stay in English for every language until the Mapbox Studio style is set to "Configured in SDK". After that change, all 11 languages are localized.

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 linhvovan29546 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 trjExpensify left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This PR has no visible effect until the Mapbox Studio style is updated

Might want to [NO QA] it then?

@linhvovan29546

Copy link
Copy Markdown
Contributor

Might want to [NO QA] it then?

Some languages have a visible effect on the native side, so we still need QA testing.

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please merge the main branch

Co-authored-by: Linh Vo <linhvovan29546@users.noreply.github.com>
@MelvinBot

Copy link
Copy Markdown
Contributor Author

I merged the latest main (336 new commits) into this branch and pushed it as merge commit 207061c. There were no conflicts.


view run

@linhvovan29546

Copy link
Copy Markdown
Contributor

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.

I opened an upstream PR to add support for these languages: rnmapbox/maps#4327.

The maintainer (thanks to @mfazekas!) split the changes into a separate PR to use setLanguage: rnmapbox/maps#4331. The new version of rnmapbox/maps will include this support, so we’ll create a separate PR to upgrade the rnmapbox/maps version in the app.

@linhvovan29546

Copy link
Copy Markdown
Contributor

@MelvinBot Please merge the main branch

@linhvovan29546

Copy link
Copy Markdown
Contributor

@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>
@MelvinBot

Copy link
Copy Markdown
Contributor Author

I merged main into this branch with no conflicts and pushed it as commit 7bcbcbf. The PR diff still covers only the 4 MapView files.


view run

@roryabraham
roryabraham merged commit df73919 into main Oct 20, 2026
42 checks passed
@roryabraham
roryabraham deleted the claude-mapboxMapLocale branch October 20, 2026 16:19
@OSBotify

Copy link
Copy Markdown
Contributor

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

@github-actions

Copy link
Copy Markdown
Contributor

🚧 roryabraham has triggered a test Expensify/App build. You can view the workflow run here.

@OSBotify

Copy link
Copy Markdown
Contributor

🚀 Deployed to staging by https://github.com/roryabraham in version: 9.5.15-1 🚀

platform result
🕸 web 🕸 success ✅
🤖 android 🤖 success ✅
🍎 iOS 🍎 success ✅

@MelvinBot

Copy link
Copy Markdown
Contributor Author

No help site update is needed. Map labels now follow the language you already set, which matches what users expect, and no sentence in docs/articles is made wrong by this change. The Account Settings article still describes the language setting correctly.


view run

@OSBotify

Copy link
Copy Markdown
Contributor

🚀 Deployed to production by https://github.com/grgia in version: 9.5.15-3 🚀

platform result
🕸 web 🕸 success ✅
🤖 android 🤖 success ✅
🍎 iOS 🍎 success ✅

Bundle Size Analysis (Sentry):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Melvin-Test-Android Melvin-Test-Web Triggers Melvin to run the testing steps of the PR on web

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants