Tile source to support multilingual maps


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
40Apr 1, 2019Feb 10, 2017Minified + gzip package size for @kartotherian/babel in KB


Build Status Coverage Status


Tile source to restructure vector PBFs for multilingual usecases, such as convert a single JSON object into multiple key/values, or to replace all language key/value names with a single one.

Usage examples

Tile is generated with 'name_' field set a JSON-encoded key-value object. Babel can be used to convert that tile to a tile, with each value in the object becoming a tag of its own, e.g. 'name_en', 'name_fr', ... . Also, babel can be used to replace multiple 'name_lang' tags with a single 'name_' tag right before rendering it, choosing the best language based on the fallback rules, but only if it is different from the 'name' tag.

# Process tiles from 'gen' source, expanding json string into multiple tags
  uri: json2tags://
    source: {ref: gen}
    tag: name   # optional, 'name' is the default
# Process tiles from 'store' source, replacing all 'name_*' tags with a single 'name' tag
  uri: babel://
    source: {ref: store}
    # optional, 'name' is the default
    tag: name
    # optional, used by default if no 'lang' code is passed to getAsync()
    defaultLanguage: 'en' 
    # optional map of fallback values. Can be a json file or an object value
    languageMap: '/my/path/fallback.json'
    # -- OR --
      en: ['fr', 'es', 'de']
      ru: ['be']

Language resolution

For babel://, the language of the name_ is chosen based on these rules:

getAsync({z,x,y, lang:'xx'):

  • name_xx
  • Use explicitly set fallbacks from the languageMap
  • Use any name_yy-Script where Script is the script of xx. E.g. if lang=ru, pick any lang_yy-Cyrl.
  • If xx uses the Latin script, use any name_zz_rm
  • name


Babel gets the CLDR defined script name (Latn, Cyrl, ... ) based on the language code. It also uses a few overrides from the overrides.json. This file should be updated with any language IDs found in OSM data.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.