mapbox / mapbox/mapbox-gl-js

setConfigProperty('basemap', 'language', ...) silently fails in v3.18 — docs should reference setLanguage()

Open
#13,630 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

auto-triaged docs :scroll:
Dominant language
TypeScript
Stars
12.4k
Forks
2.4k
PR merge metrics
No merged PRs in 30d

Description

## Description

`setConfigProperty('basemap', 'language', ...)` silently does nothing in mapbox-gl v3.18.1 with the Standard style (`mapbox://styles/mapbox/standard`). The call succeeds without error, but `getConfigProperty('basemap', 'language')` returns `null` and the map labels remain in the default language.

The working API is `map.setLanguage()` (or the `language` constructor option), but this isn't obvious from the current documentation.

## Steps to reproduce

```js
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/standard',
});

map.on('load', () => {
// This silently does nothing:
map.setConfigProperty('basemap', 'language', 'ko');

console.log(map.getConfigProperty('basemap', 'language')); // null
console.log(map.getStyle().imports[0].schema); // undefined
console.log(map.getStyle().imports[0].config); // undefined

// This works:
map.setLanguage('ko'); // labels switch to Korean
});
```

## Debug findings

| API | Result |
|-----|--------|
| `setConfigProperty('basemap', 'language', 'ko')` | No error, but `getConfigProperty` returns `null`. Labels stay English. |
| `new Map({ config: { basemap: { language: 'ko' } } })` | Silently ignored. |
| `map.setLanguage('ko')` | **Works.** Labels switch to Korean. |
| `map.getStyle().imports[0].schema` | `undefined` (basemap has no config schema) |

## Documentation gap

The following docs reference `setConfigProperty` or the `config` constructor option for changing Standard style language, which doesn't work:

- https://docs.mapbox.com/help/dive-deeper/change-language/ — references `setConfigProperty` for Standard style
- https://docs.mapbox.com/mapbox-gl-js/guides/standard-style/ — shows `config.basemap.language` pattern

The working APIs (`map.setLanguage()` / `new Map({ language: 'ko' })`) were noted in #12950 but aren't prominent in the main docs.

## Expected behavior

Either:
1. `setConfigProperty('basemap', 'language', ...)` should work as documented, or
2. The docs should clearly reference `map.setLanguage()` as the correct API for Standard style

## Environment

- mapbox-gl: 3.18.1
- Style: `mapbox://styles/mapbox/standard`
- Browser: Chrome (macOS)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the change-language help page and Standard style guide linked in the issue, comparing their language examples with the reproduced setConfigProperty, config, and setLanguage calls. Done means both pages clearly identify setLanguage() and the language constructor option as the working APIs for Standard style, without presenting the non-working configuration paths as valid.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.