Skip to content

Latest commit

 

History

History
83 lines (59 loc) · 7.8 KB

CONTRIBUTING.md

File metadata and controls

83 lines (59 loc) · 7.8 KB
Raw

Contributing to OSRM Text Instructions

Reporting an issue

Bug reports and feature requests are more than welcome, but please consider the following tips so we can respond to your feedback more effectively.

Before reporting a bug here, please determine whether the problem is due to OSRM Text Instructions itself or if the problem is in a related product:

When reporting a bug in the navigation SDK itself, please provide:

  • The OSRM Text Instructions version number
  • The language being used, if the issue is specific to a language
  • A demonstration of the problem, either a link to a route on the OSRM demo server or sample code

Opening a pull request

Pull requests are appreciated. If your PR includes any changes that would impact developers or end users, please mention those changes in the “master” section of CHANGELOG.md, noting the PR number. Examples of noteworthy changes include new features, fixes for user-visible bugs, and renamed or deleted public symbols.

Adding a new feature

The development language of this project is English (en). To ensure that a new feature is functional regardless of the language in use, you also need to add any strings that the feature uses to all the localizations, not just English:

  • If the new string is similar to an existing string, duplicate the existing string in the same localization to fill in the missing string.
  • If no existing string is similar, copy the English string to fill in the missing string.

This way, the instruction is more likely to make sense to the user even if it’s imperfect. Once the feature is merged, we rely on translators to update their localizations with better translations.

This library relies on automatically generated test fixtures to show the effect your changes have on this library’s output in each language:

  • To update the instructions in the fixture files, run UPDATE=1 npm test.
  • To create new fixtures, add them to test/fixtures_test.js, then run UPDATE=1 npm test.
  • Integration tests based on these fixtures help to prevent unexpected regressions. Run the integration tests using npm install && npm test.

Adding or updating a localization

We welcome your help in making OSRM Text Instructions available in the languages that you and your users speak. Localizations are maintained at Transifex, then committed to the languages/ folder of this repository when ready. If your language already has a translation, feel free to complete or proofread it. Otherwise, please request your language so you can start translating. Transifex has a Web interface, so you don’t need specialized software to get started.

Once you’ve finished translating OSRM Text Instructions into a new language in Transifex, open an issue in this repository asking to pull in your localization. Or do it yourself and open a pull request with the results:

  1. (First time only.) Create a plain text file named transifex.auth, and it put in the root folder of this repository. (This file is ignored by Git, so you don’t need to worry about accidentally committing it.) Fill in your Transifex credentials: 
    {
    "user": "username",
    "pass": "password"
}
  2. (First time only.) Create an empty translation file by running echo "{}" > languages/translations/xyz.json, where xyz is a language code, such as en, fil, pt-BR, or zh-Hant.
  3. (First time only.) In languages.js, require the new file and add an entry for xyz to the instructions variable.
  4. Pull the translations from Transifex by running npm run transifex.
  5. (Optional.) If your language has special casing rules or you need to systematically change what’s imported from Transifex, add an override file to languages/overrides/xyz.json.
  6. (Optional.) Add an abbreviation file to languages/abbreviations/xyz.json that determines how words in road names and place names can be abbreviated when instructions are displayed visually.
  7. (Optional.) Add a grammar file to languages/grammar/xyz.json that specifies the declension rules to apply to road and place names in a sentence.
  8. Generate test fixtures for the language by running UPDATE=1 npm test. Run git diff to inspect the changes; make sure your translations make sense in the context of a complete sentence. Once you’re satisfied with the results, commit and push your changes.

After we merge the PR containing your localization updates and release a new version of OSRM Text Instructions, the Mapbox Directions API will begin to accept the new language in the language query parameter. If you also want the OSRM demo server to display instructions in the new language, add the language to osrm-frontend.

Related projects

Please consider also translating the following related projects, which work together with OSRM Text Instructions to give the user a complete turn-by-turn navigation experience:

Releasing a new version

  1. In CHANGELOG.md, replace the “master” heading with the new version number.
  2. Bump the version in package.json.
  3. Run git commit -a | "vx.y.z", including a list of changes from the changelog in the commit message.
  4. Run git tag vx.y.z -a, including the same list in the tag message.
  5. Run git push && git push --tags to push the changes to the repository.
  6. Open a pull request, get a review, and merge to master. (master is a protected branch.)
  7. Run npm publish to publish the package to the general public.