Mapbox GL Language

Adds support for switching the language of your map style in Mapbox GL JS maps.

Requires mapbox-gl-js. For other platforms, such as Android and iOS, see this help document.

Automatic style transformations for different languages

Switch language based on user agent

Usage

mapbox-gl-language is a Mapbox GL JS plugin that you can easily add on top of your map.

When using a CDN

    <script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-language/v1.0.0/mapbox-gl-language.js'></script>

When using modules

Check how to use Mapbox GL JS in a module bundler.

npm install --save mapbox-gl @mapbox/mapbox-gl-language

import mapboxgl from 'mapbox-gl';
import MapboxLanguage from '@mapbox/mapbox-gl-language';

Example

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';
const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v10',
    center: [-77.0259, 38.9010],
    zoom: 9
});

// Add RTL support if you want to support Arabic
// mapboxgl.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.10.1/mapbox-gl-rtl-text.js');

const language = new MapboxLanguage();
map.addControl(language);

Check examples/ for more usage examples.

API

Table of Contents

• MapboxLanguage
  • Parameters
  • setLanguage
    • Parameters

MapboxLanguage

Create a new Mapbox GL JS plugin that modifies the layers of the map style to use the text-field that matches the browser language. As of Mapbox GL Language v1.0.0, this plugin no longer supports token values (e.g. {name}). v1.0+ expects the text-field property of a style to use an expression of the form ['get', 'name_en'] or ['get', 'name']; these expressions can be nested. Note that get expressions used as inputs to other expressions may not be handled by this plugin. For example:

["match",
  ["get", "name"],
  "California",
  "Golden State",
  ["coalesce",
    ["get", "name_en"],
    ["get", "name"]
  ]
]

Only styles based on Mapbox v8 styles are supported.

Parameters

• options object Options to configure the plugin.

  • options.supportedLanguages Array<string>? List of supported languages
  • options.languageTransform Function? Custom style transformation to apply
  • options.languageField RegExp RegExp to match if a text-field is a language field (optional, default /^name_/)
  • options.getLanguageField Function? Given a language choose the field in the vector tiles
  • options.languageSource string? Name of the source that contains the different languages.
  • options.defaultLanguage string? Name of the default language to initialize style after loading.
  • options.excludedLayerIds Array<string>? Name of the layers that should be excluded from translation.

setLanguage

Explicitly change the language for a style.

Parameters

• style object Mapbox GL style to modify
• language string The language iso code

Returns object the modified style

Develop

Run the linter and watch for changes to rebuild with browserify.

npm install
npm run test

Languages

Showcasing the languages supported by Mapbox Streets.

• Your Browser language
• Arabic
• Chinese Simplified
• Chinese Traditional
• English
• French
• German
• Italian
• Japanese
• Korean
• Multilingual
• Portuguese
• Russian
• Spanish
• Vietnamese

Supported Styles

You can configure the plugin to support your own custom style using style transforms and custom language fields. By default, this plugin works best with official Mapbox styles or styles derived from official Mapbox styles. The styles must be based on Mapbox v8 styles:

• mapbox://styles/mapbox/streets-v11
• mapbox://styles/mapbox/outdoors-v11
• mapbox://styles/mapbox/dark-v10
• mapbox://styles/mapbox/light-v10
• mapbox://styles/mapbox/satellite-streets-v9
• mapbox://styles/mapbox/traffic-day-v2
• mapbox://styles/mapbox/traffic-night-v2

1.0.1

Features and improvements

• Add TypeScript types. (#58 h/t @Phillip9587)

1.0.0

⚠️ Breaking changes

• Adds support for Mapbox Streets v8 vector tileset and all styles based on this tileset, such as streets-v11 and dark-v10 while removing support for Mapbox Streets v7 vector tileset-based styles. (#39)
• Removes support for Internet Explorer 11. (#39)
• Support for Streets v7 Chinese zh is replaced with Traditional Chinese zh-Hant and Simplified Chinese zh-Hans. (#39)
• Support for token values (e.g. {name}) has been removed. The plugin now expects the text-field property of a style to use an expression of the form ['get', 'name_en'] or ['get', 'name']; these expressions can be nested. Note that get expressions used as inputs to other expressions may not be handled by this plugin. For example:

  ["match",
  ["get", "name"],
  "California",
  "Golden State",
  ["coalesce",
    ["get", "name_en"],
    ["get", "name"]
  ]
  ]

  (#39)

Features and improvements

• Add support for Mapbox GL JS v2.0.0+. (#42)
• Add support for Vietnamese vi. (#43)

Bug fixes

• Remove unnecessary letter spacing transformations for Arabic. (#44)
• Prevent potential undefined errors when language input is null. (#45)
• Ensure that the selected language is retained when switching map styles. (#46)