OpenMapTiles Language

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

Requires maplibre-gl-js or older mapbox-gl-js.

Automatic style transformations for different languages

Switch language based on user agent

Example

var map = new mapboxgl.Map({
    container: 'map',
    style: 'https://raw.githubusercontent.com/openmaptiles/osm-bright-gl-style/gh-pages/style-local.json',
    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');

// Language can be fixed at initialization or not
const languageControl = new OpenMapTilesLanguage({
    defaultLanguage: 'it',
})
map.addControl(languageControl);

// Language can be set later
languageControl.setLanguage('es');

Check examples/ for more usage examples.

Usage

The project is bundled in several formats so you can use it everywhere.

If you don't know what format is better for you, choose UMD ;)

UMD (Universal Module Definition)

To use in your HTML files:

<script
  type="text/javascript"
  src="https://unpkg.com/@teritorio/openmaptiles-gl-language/dist/openmaptiles_gl_language.umd.production.min.js"
></script>

CommonJS

To import the library in your bundled project:

import { OpenMapTilesLanguage } from '@teritorio/openmaptiles-gl-language'

const languageControl = new OpenMapTilesLanguage({
    defaultLanguage: 'it',
});
map.addControl(languageControl);

ES Module

<script type="module">
import { OpenMapTilesLanguage } from 'https://unpkg.com/@teritorio/openmaptiles-gl-language/dist/openmaptiles_gl_language.esm.js';

const languageControl = new OpenMapTilesLanguage();
map.addControl(languageControl);
</script>

API

Table of Contents

• OpenMapTilesLanguage
  • Parameters
  • setLanguage
    • Parameters

OpenMapTilesLanguage

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.

Parameters

• options object Options to configure the plugin.
  • options.supportedLanguages Array<string>? List of supported languages
  • 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

• 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 OpenMapTiles.

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

Or manual switch.

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 OpenMapTiles styles or derived.