setConfigProperty('basemap', 'language', ...) silently fails in v3.18 — docs should reference setLanguage()
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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