OSRM Text Instructions
OSRM Text Instructions transforms OSRM route responses into localized text instructions. This repository contains the canonical implementation of this library written in JavaScript. OSRM Text Instructions is also available in Swift and Objective-C and experimentally in Java.
OSRM Text Instructions has been translated into several languages. Please help us add support for the languages you speak using Transifex.
Design goals
- Cross platform Use a data-driven approach that makes implementations in other programming environments easy to write
- Test suite Have a data-driven test suite with fixtures which can be used cross-platform
- Translation Allow for translations via Transifex
- Customization Users should be able to easily fork or monkey-patch the results to adjust to their own liking
JavaScript Usage
var version = 'v5';
var osrmTextInstructions = require('osrm-text-instructions')(version);
var language = 'en';
response.legs.forEach(function(leg) {
leg.steps.forEach(function(step) {
instruction = osrmTextInstructions.compile(language, step, options)
});
});
Parameters require('osrm-text-instructions')(version, options)
parameter | required? | values | description |
---|
version | required | v5 | Major OSRM version |
options.hooks.tokenizedInstruction | optional | function(instruction) | A function to change the raw instruction string before tokens are replaced. Useful to inject custom markup for tokens |
Parameters compile(language, step, options)
parameter | required? | values | description |
---|
language | required | en de zh-Hans fr nl ru and more | Compiling instructions for the selected language code. |
step | required | OSRM route step object | The RouteStep as it comes out of OSRM |
options | optional | Object with 2 keys: legIndex and legCount , both having integer values. Used for giving instructions for arriving at waypoints. | |
Development
Architecture
index.js
holds the main transformation logic in javascriptinstructions/
holds the translateable strings
Tests
Tests are data-driven integration tests for the english language.
To run them yourself for the JavaScript implementation:
npm install
npm test
Generate Fixtures
Fixtures are programatically created and updated via test/fixtures_test
. To update the instructions in the fixture files, run UPDATE=1 npm test
. To create new fixtures, add them to test/fixtures_test
, then run UPDATE=1 npm test
.
Translations
The main language of this project is English en
. We support other languages via translations, as seen in languages/translations
.
You can help translating on the web via Transifex
To add an own translations:
- Go to Transifex and create the new translation there
- When the translation on Transifex is ready, pull in the translation file:
- Create an empty translation file
echo "{}" > languages/translations/{language_code}.json
- Add the new translation file and language code to
./languages.js
- If needed: make overrides in
languages/overrides/{language_code}.json
npm run transifex
- Generate fixture strings for the tests via
UPDATE=1 npm test
(see changes in git diff
) - Make a PR
Release
git checkout master
- Update CHANGELOG.md
- Bump version in package.json
git commit -am "vx.y.z"
with Changelog list in commit messagegit tag vx.y.z -a
with Changelog list in tag messagegit push origin master; git push origin --tags
npm publish