Contributing to the Mapbox Navigation SDK for iOS
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 issue lies with the navigation SDK itself or with another Mapbox product:
- For general questions and troubleshooting help, please contact the Mapbox support team.
- Report problems with the map’s contents or routing problems, especially problems specific to a particular route or region, using the Mapbox Feedback tool.
- Report problems in guidance instructions in the OSRM Text Instructions repository.
When reporting a bug in the navigation SDK itself, please indicate:
- The navigation SDK version
- Whether you installed the SDK using CocoaPods or Carthage
- The iOS version, iPhone model, and Xcode version, as applicable
- Any relevant language settings
Building the SDK
To build this SDK, you need Xcode 9 and Carthage:
carthage bootstrap --platform iOS --cache-builds.
- Once the Carthage build finishes, open
MapboxNavigation.xcodeprojin Xcode and build the MapboxNavigation scheme.
See the README for instructions on building and running the included Swift and Objective-C example projects.
Testing the SDK
It is important to test the SDK using the
iPhone 8 Plus simulator for the
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, renamed or deleted public symbols, and changes that affect bridging to Objective-C.
Making any symbol public
To add any type, constant, or member to the SDK’s public interface:
- Ensure that the symbol bridges to Objective-C and does not rely on any language features specific to Swift – so no namespaced types or classes named with emoji!
- Name the symbol according to Swift design guidelines and Cocoa naming conventions.
@objc(…)to specify an Objective-C-specific name that conforms to Objective-C naming conventions. Use the
MBclass prefix to avoid conflicts with client code.
- Provide full documentation comments. We use jazzy to produce the documentation found on the website for this SDK. Many developers also rely on Xcode’s Quick Help feature, which supports a subset of Markdown.
- (Optional.) Add the type or constant’s name to the relevant category in the
custom_categoriessection of the jazzy configuration file. This is required for classes and protocols and also recommended for any other type that is strongly associated with a particular class or protocol. If you leave out this step, the symbol will appear in an “Other” section in the generated HTML documentation’s table of contents.
Adding image assets
Image assets are designed in a PaintCode document managed in the navigation-ui-resources repository. After changes to that repository are merged, export the PaintCode drawings as Swift source code and add or replace files in the MapboxNavigation folder.
Adding user-facing text
To add or update text that the user may see in the navigation SDK:
- Use the
NSLocalizedString("UNIQUE_IDENTIFIER", bundle: .mapboxNavigation, value: "What English speakers see", comment: "Where this text appears or how it is used")
- (Optional.) If you need to embed some text in a string, use
String.localizedStringWithFormat(NSLocalizedString("UNIQUE_IDENTIFIER", bundle: .mapboxNavigation, value: "What English speakers see with %@ for each embedded string", comment: "Format string for a string with an embedded string; 1 = the first embedded string"), embeddedString)
- (Optional.) When dealing with a number followed by a pluralized word, do not split the string. Instead, use a format string and make
%d file(s). Then pluralize for English in the appropriate .stringsdict file. See MapboxNavigation/Resources/en.lproj/Localizable.stringsdict for an example. Localizers should do likewise for their languages.
scripts/extract_localizable.shto add the new text to the .strings files.
- Open a pull request with your changes. Once the pull request is merged, Transifex will pick up the changes within a few hours.
Adding or updating a localization
The Mapbox Navigation SDK for iOS features several translations contributed through Transifex. If your language already has a translation, feel free to complete or proofread it. Otherwise, please request your language so you can start translating. Note that we’re primarily interested in languages that iOS supports as system languages.
While you’re there, please consider also translating the following related projects:
- Mapbox Maps SDK for iOS, which is responsible for the map view and minor UI elements such as the compass (instructions)
- OSRM Text Instructions, which the Mapbox Directions API uses to generate textual and verbal turn instructions (instructions)
- Mapbox Navigation SDK for Android, the analogous library for Android applications (instructions)
Once you’ve finished translating the iOS navigation SDK 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:
- (First time only.) Download the
txcommand line tool and configure your .transifexrc.
- In MapboxNavigation.xcodeproj, open the project editor. Using the project editor’s sidebar or tab bar dropdown, go to the “MapboxNavigation” project. Under the Localizations section of the Info tab, click the + button to add your language to the project.
- In the sheet that appears, select all the files, then click Finish.
The .strings files should still be in the original English – that’s expected. Now you can pull your translations into this repository:
tx pull -ato fetch translations from Transifex. You can restrict the operation to just the new language using
tx pull -l xyz, where xyz is the language code.
- To facilitate diffing and merging, convert any added .strings files from UTF-16 encoding to UTF-8 encoding. You can convert the file encoding using Xcode’s File inspector or by running
- For each of the localizable files in the project, open the file, then, in the File inspector, check the box for your new localization.