feat(localization): add 3D map localization sample across Kotlin, Java, Compose and Snippets by LoyalAbbas · Pull Request #74 · googlemaps-samples/android-maps3d-samples

LoyalAbbas · 2026-09-24T05:18:30Z

Adds the Maps Localization sample demonstrating dynamic 3D map language and region localization using LocaleOptions and GoogleMap3D.setLocale(LocaleOptions) across Kotlin Views, Java Views, Jetpack Compose, and Snippets.

Key Changes

Shared Clean Architecture Layer (:Maps3DSamples:ApiDemos:common):
- Added LocalizationData.kt (MapLocalePreset, LocalizationState, DEFAULT_LOCALIZATION_CAMERA) with curated locale presets (en-US, zh-CN, fr-FR, ja-JP, es-ES, ar-SA, de-DE, and SYSTEM_DEFAULT) and toLocaleOptions() mapping.
- Added LocalizationController.kt state machine and MapsLocalizationViewModel.kt exposing StateFlow (for Kotlin/Compose) and LiveData via asLiveData() (for Java Views).
- Added shared control panel layout (control_panel_maps_localization.xml) and localized string resources (strings.xml).
3-Way Feature Parity:
- Kotlin Views (:Maps3DSamples:ApiDemos:kotlin-app): Added MapsLocalizationActivity.kt extending SampleBaseActivity and registered in MainActivity.kt / AndroidManifest.xml.
- Java Views (:Maps3DSamples:ApiDemos:java-app): Added MapsLocalizationActivity.java extending SampleBaseActivity and registered in MainActivity.java / AndroidManifest.xml.
- Jetpack Compose (:Maps3DSamples:ComposeDemos:app): Added MapsLocalizationActivity.kt with MapsLocalizationScreen and LocalizationControlCard composables, registered in MainActivity.kt / AndroidManifest.xml.
Documentation Snippets (:snippets:kotlin-app & :snippets:java-app):
- Added MapLocalizationSnippets.kt and MapLocalizationSnippets.java with region tags (maps_android_3d_localization_*) demonstrating LocaleOptions and map.setLocale(localeOptions).
- Added setLocale(LocaleOptions) pass-through to TrackedMap3D.kt and TrackedMap3D.java and registered the snippet group in SnippetRegistry.
Testing Suite:
- Added Tier 2 & Tier 3 unit tests (LocalizationControllerTest.kt, MapsLocalizationViewModelTest.kt).
- Added Tier 4 visual regression tests (MapsLocalizationVisualTest.kt, MapsLocalizationVisualTest.java).

Verification

Verified :Maps3DSamples:ApiDemos:common:testDebugUnitTest unit tests pass.
Verified Kotlin Views, Java Views, Jetpack Compose, and Snippets compile and format cleanly with spotlessApply.
Verified runtime language and region switching updates 3D map labels in-place without recreating Map3DView.

dkhawk

Summary & Verification

LGTM! Excellent work on this feature.

100% 3-way language parity across Kotlin Views, Java Views, Jetpack Compose, and interactive Snippets is fully verified. We tested this build on a physical Pixel 6 (using the 16.0.0 RC artifact in local Maven) and confirmed that:

Runtime Localization: Language and region switching via GoogleMap3D.setLocale(LocaleOptions) successfully updates 3D map tile labels in-place without reloading the scene or recreating Map3DView.
Architecture & Tests: Clean separation of concerns (Data -> Controller -> ViewModel -> Views). All Tier 2 and Tier 3 unit tests (LocalizationControllerTest, MapsLocalizationViewModelTest) pass with 100% success rate.
Snippet Region Tags: Interactive documentation samples in snippets/ strictly follow Google documentation region tags (maps_android_3d_localization_*).
CI Status: The 4 failing CI jobs on GitHub Actions are an expected external artifact of the parent branch stack (#67) pending the public GMaven publication of play-services-maps3d:16.0.0.

Left two minor polish suggestions inline regarding dynamic SYSTEM_DEFAULT resolution and Compose effect keying. Approving the PR!

dkhawk · 2026-09-29T19:27:07Z

+    SYSTEM_DEFAULT(
+        displayName = "System Default",
+        nativeLabel = SYSTEM_DEFAULT_CODE,
+        language = Locale.getDefault().language,
+        region = Locale.getDefault().country,
+    )


In MapLocalePreset.SYSTEM_DEFAULT, language and region are evaluated once at class initialization time as constructor arguments (Locale.getDefault().language / country). If a user changes their device system language in Android Settings while the app process is cached in memory, this enum constant will retain the stale initial locale.

Consider making language and region dynamic custom property accessors on MapLocalePreset so that selecting SYSTEM_DEFAULT always queries Locale.getDefault() dynamically:

// [START maps_android_3d_localization_preset_dynamic_locale] enum class MapLocalePreset( val displayName: String, val nativeLabel: String, private val rawLanguage: String? = null, private val rawRegion: String? = null, ) { ENGLISH_US("English (US)", "en-US", "en", "US"), CHINESE_CHINA("Chinese (China)", "中文 (zh-CN)", "zh", "CN"), FRENCH_FRANCE("French (France)", "Français (fr-FR)", "fr", "FR"), JAPANESE_JAPAN("Japanese (Japan)", "日本語 (ja-JP)", "ja", "JP"), SPANISH_SPAIN("Spanish (Spain)", "Español (es-ES)", "es", "ES"), ARABIC_SAUDI_ARABIA("Arabic (Saudi Arabia)", "العربية (ar-SA)", "ar", "SA"), GERMAN_GERMANY("German (Germany)", "Deutsch (de-DE)", "de", "DE"), SYSTEM_DEFAULT("System Default", SYSTEM_DEFAULT_CODE); val language: String get() = rawLanguage ?: Locale.getDefault().language val region: String get() = rawRegion ?: Locale.getDefault().country } // [END maps_android_3d_localization_preset_dynamic_locale]

dkhawk · 2026-09-29T19:27:07Z

+    LaunchedEffect(googleMap3DInstance, state.selectedPreset) {
+        googleMap3DInstance?.setLocale(state.toLocaleOptions())
+    }


In MapsLocalizationScreen, LaunchedEffect is keyed on (googleMap3DInstance, state.selectedPreset). Keying on (googleMap3DInstance, state.languageCode, state.regionCode) (or state.toLocaleOptions()) directly decouples the effect from preset selection, ensuring that any custom locale modifications trigger the in-place map update even if selectedPreset does not change:

// [START maps_android_3d_localization_compose_sync_suggested] LaunchedEffect(googleMap3DInstance, state.languageCode, state.regionCode) { googleMap3DInstance?.setLocale(state.toLocaleOptions()) } // [END maps_android_3d_localization_compose_sync_suggested]

kikoso

Can you take a look at the comments, @LoyalAbbas ? Thanks! The CI failures are not related to GMaven: MainActivityTest fails, and the PlacesUIKit3D Spotless issue is already fixed on the base branch, so a rebase should take care of that one.

kikoso · 2026-10-14T06:39:25Z

        put(R.string.feature_title_roadmap_mode, RoadmapModeActivity.class);
        put(R.string.feature_title_field_of_view, FieldOfViewActivity.class);
        put(R.string.feature_title_projection_3d, Projection3DActivity.class);
+        put(R.string.feature_title_maps_localization, MapsLocalizationActivity.class);


This makes MainActivityTest.testSampleActivitiesContainsAllSamples fail, since it still expects hasSize(23). Could we bump it to 24 and add a contains(MapsLocalizationActivity.class) check like the other samples have?

kikoso · 2026-10-14T06:39:25Z

+                modifier = Modifier.fillMaxSize(),
+                onMapReady = { map ->
+                    googleMap3DInstance = map
+                    map.setLocale(state.toLocaleOptions())


The LaunchedEffect keyed on googleMap3DInstance already applies the locale as soon as the instance is set, so we end up calling setLocale twice on startup. Should we keep only one of them?

kikoso · 2026-10-14T06:39:25Z

+        description = "Applies language='zh' and region='CN' via LocaleOptions and setLocale.",
+    )
+    fun setChineseLocalization() {
+        // [START maps_android_3d_localization_init_kt]


Region tags end up in the devsite docs and are painful to rename later. init and runtime don't say much next to japanese and default. What about maps_android_3d_localization_chinese_kt / _french_kt (and the same for Java)?

kikoso · 2026-10-14T06:39:25Z

+
+    private fun showLanguageSelectionDialog() {
+        val presets = MapLocalePreset.entries
+        val labels = presets.map { "${it.displayName} — ${it.nativeLabel}" }.toTypedArray()


nit: could we move this label to a string resource, like we did with language_button_format? The same format is hardcoded in the Java and Compose versions too.

kikoso · 2026-10-14T06:39:25Z

+                    IconButton(onClick = onNavigateUp) {
+                        Icon(
+                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
+                            contentDescription = null,


nit: the back button has no contentDescription, so TalkBack will not announce it.

kikoso

LGTM! Thanks for addressing the comments, @LoyalAbbas !

…a, Compose, and Snippets

…region tags

# [1.17.0](v1.16.0...v1.17.0) (2026-10-14) ### Features * **localization:** add 3D map localization sample across Kotlin, Java, Compose and Snippets ([#74](#74)) ([04bc6b9](04bc6b9))

googlemaps-bot · 2026-10-14T12:34:51Z

🎉 This PR is included in version 1.17.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

LoyalAbbas requested a review from dkhawk September 24, 2026 05:18

LoyalAbbas added this pull request to stack #75 September 24, 2026 05:18

dkhawk approved these changes Sep 29, 2026

View reviewed changes

LoyalAbbas marked this pull request as ready for review October 13, 2026 12:45

LoyalAbbas force-pushed the feat/maps_localization branch from be9e88b to 6e9ccce Compare October 13, 2026 13:12

LoyalAbbas marked this pull request as draft October 13, 2026 13:42

LoyalAbbas marked this pull request as ready for review October 14, 2026 05:16

kikoso requested changes Oct 14, 2026

View reviewed changes

LoyalAbbas force-pushed the feat/maps_localization branch 2 times, most recently from 7d0bd3c to 0aefc3a Compare October 14, 2026 08:40

kikoso approved these changes Oct 14, 2026

View reviewed changes

Base automatically changed from feat/upgrade_to_16.0.0 to main October 14, 2026 08:43

LoyalAbbas force-pushed the feat/maps_localization branch 2 times, most recently from 4b5b408 to 2f69ed7 Compare October 14, 2026 12:00

LoyalAbbas added 3 commits October 14, 2026 17:46

feat(localization): add 3D map localization sample across Kotlin, Jav…

28ef6ff

…a, Compose, and Snippets

fix(localization): resolve PR comments

aeb79fc

fix(localization): address PR review feedback on tests, strings, and …

0638de9

…region tags

LoyalAbbas force-pushed the feat/maps_localization branch from 2f69ed7 to 0638de9 Compare October 14, 2026 12:16

LoyalAbbas merged commit 04bc6b9 into main Oct 14, 2026
12 checks passed

LoyalAbbas deleted the feat/maps_localization branch October 14, 2026 12:26

googlemaps-bot added the released label Oct 14, 2026

Navigation Menu

Repository navigation

feat(localization): add 3D map localization sample across Kotlin, Java, Compose and Snippets - #74

feat(localization): add 3D map localization sample across Kotlin, Java, Compose and Snippets#74
LoyalAbbas merged 3 commits into
mainfrom
feat/maps_localization

LoyalAbbas commented Sep 24, 2026

Uh oh!

dkhawk left a comment

Uh oh!

dkhawk Sep 29, 2026

Uh oh!

dkhawk Sep 29, 2026

Uh oh!

kikoso left a comment

Uh oh!

kikoso Oct 14, 2026

Uh oh!

kikoso Oct 14, 2026

Uh oh!

kikoso Oct 14, 2026

Uh oh!

kikoso Oct 14, 2026

Uh oh!

kikoso Oct 14, 2026

Uh oh!

kikoso left a comment

Uh oh!

Uh oh!

googlemaps-bot commented Oct 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

LoyalAbbas commented Sep 24, 2026

Key Changes

Verification

Uh oh!

dkhawk left a comment

Choose a reason for hiding this comment

Summary & Verification

Uh oh!

dkhawk Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

dkhawk Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso left a comment

Choose a reason for hiding this comment

Uh oh!

kikoso Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

kikoso left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

googlemaps-bot commented Oct 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants