diff --git a/README.md b/README.md index 129771f9bdf..41d889cf15b 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,10 @@ We run a speed test (included in the code) to measure the performance for every ## Repository layout -The main Java server code is in `src/main/`. OTP also includes a Javascript client based on the -Leaflet mapping library in `src/client/`. This client is now primarily used for testing, with most -major deployments building custom clients from reusable components. The Maven build produces a -unified ("shaded") JAR file at `target/otp-VERSION.jar` containing all necessary code and -dependencies to run OpenTripPlanner. +The main Java server code is in `application/src/main/`. OTP also includes a Javascript client based on the +MapLibre mapping library in `client/src/`. This client is now used for testing, with most major +deployments building custom clients from reusable components. The Maven build produces a unified ("shaded") +JAR file at `application/target/otp-VERSION.jar` containing all necessary code and dependencies to run OpenTripPlanner. Additional information and instructions are available in the [main documentation](http://docs.opentripplanner.org/en/dev-2.x/), including a diff --git a/client/README.md b/client/README.md index 54971062971..a646cd1170c 100644 --- a/client/README.md +++ b/client/README.md @@ -22,7 +22,7 @@ generated during build and are not checked into the repository. Use latest LTS version of Node/npm (currently v18). Recommend using a version manager such as `nvm`. The dev and production builds require graphql schema to be present at -`../src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql`. +`../application/src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql`. ## Getting started (development) diff --git a/client/codegen.ts b/client/codegen.ts index b5b68a0650a..60299a21a97 100644 --- a/client/codegen.ts +++ b/client/codegen.ts @@ -2,7 +2,7 @@ import type { CodegenConfig } from '@graphql-codegen/cli'; const config: CodegenConfig = { overwrite: true, - schema: '../src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql', + schema: '../application/src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql', documents: 'src/**/*.{ts,tsx}', generates: { 'src/gql/': { diff --git a/doc/templates/BuildConfiguration.md b/doc/templates/BuildConfiguration.md index 77b03dae500..3d1cd5a1db3 100644 --- a/doc/templates/BuildConfiguration.md +++ b/doc/templates/BuildConfiguration.md @@ -163,7 +163,7 @@ OTP allows you to adjust the elevation values reported in API responses in two w is to store ellipsoid (GPS) elevation values internally, but apply a single geoid difference value in the OTP client where appropriate to display elevations above sea level. This ellipsoid to geoid difference is returned in each trip plan response in the -[ElevationMetadata](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/api/resource/ElevationMetadata.java) +[ElevationMetadata](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/ext/java/org/opentripplanner/ext/restapi/model/ElevationMetadata.java) field. Using a single value can be sufficient for smaller OTP deployments, but might result in incorrect values at the edges of larger OTP deployments. If your OTP instance uses this, it is recommended to set a default request value in the `router-config.json` file as follows: diff --git a/doc/templates/GraphQL-Tutorial.md b/doc/templates/GraphQL-Tutorial.md index 2a78be65cc2..b3a59b7d19e 100644 --- a/doc/templates/GraphQL-Tutorial.md +++ b/doc/templates/GraphQL-Tutorial.md @@ -51,4 +51,4 @@ Most people want to get routing results out of OTP, so lets see the query for th Again, please use the autocomplete and documentation viewers to figure out what each input parameter and property means. -More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/test/resources/org/opentripplanner/apis/gtfs/queries). \ No newline at end of file +More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/application/src/test/resources/org/opentripplanner/apis/gtfs/queries). \ No newline at end of file diff --git a/doc/templates/RouterConfiguration.md b/doc/templates/RouterConfiguration.md index 87e4c1693cc..42a78cc41ca 100644 --- a/doc/templates/RouterConfiguration.md +++ b/doc/templates/RouterConfiguration.md @@ -14,7 +14,7 @@ These options can be applied by the OTP server without rebuilding the graph. Certain settings can be provided on the command line, when starting OpenTripPlanner. See the `CommandLineParameters` class -for [a full list of arguments](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/standalone/config/CommandLineParameters.java) +for [a full list of arguments](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/main/java/org/opentripplanner/standalone/config/CommandLineParameters.java) . ## Routing defaults diff --git a/doc/user/BuildConfiguration.md b/doc/user/BuildConfiguration.md index f5281db0f4e..99e98066e73 100644 --- a/doc/user/BuildConfiguration.md +++ b/doc/user/BuildConfiguration.md @@ -264,7 +264,7 @@ OTP allows you to adjust the elevation values reported in API responses in two w is to store ellipsoid (GPS) elevation values internally, but apply a single geoid difference value in the OTP client where appropriate to display elevations above sea level. This ellipsoid to geoid difference is returned in each trip plan response in the -[ElevationMetadata](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/api/resource/ElevationMetadata.java) +[ElevationMetadata](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/ext/java/org/opentripplanner/ext/restapi/model/ElevationMetadata.java) field. Using a single value can be sufficient for smaller OTP deployments, but might result in incorrect values at the edges of larger OTP deployments. If your OTP instance uses this, it is recommended to set a default request value in the `router-config.json` file as follows: diff --git a/doc/user/Frontends.md b/doc/user/Frontends.md index 8bb32273149..ac793a4fc85 100644 --- a/doc/user/Frontends.md +++ b/doc/user/Frontends.md @@ -19,7 +19,7 @@ On the other hand, **production frontends** are intended to be a component of la The main OpenTripPlanner repository currently contains two debug web frontends: - new one currently under development at [`/client`](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/client). -- the classic one in [`/src/client/classic-debug/`](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/client/classic-debug) +- the classic one in [`/application/src/client/classic-debug/`](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/application/src/client/classic-debug) The **new debug client** is a React/TypeScript Single Page App (SPA) that can be served locally or accessed over a content delivery network (CDN). Unlike the original debug client, it connects to the OTP Java backend via the GraphQL API using the Transmodel vocabulary. By default, it is available at the root URL (`http://localhost:8080/` in local operation). @@ -29,7 +29,7 @@ It connects to the OTP Java backend via a REST API using the GTFS vocabulary. Hi It is still available, but has been moved to `http://localhost:8080/classic-debug/` . There is a third piece of software that might qualify as an OTP client: a Java Swing application making use of the Processing visualization library, -located in the [GraphVisualizer class](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/visualizer/GraphVisualizer.java). +located in the [GraphVisualizer class](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/main/java/org/opentripplanner/visualizer/GraphVisualizer.java). While it would not be accurate to call this a "native" desktop application (as it's cross-platform Java) it is not a web app. This very developer-centric UI is also over a decade old and has been very sparsely maintained, but continues to exist because it can visualize the progress of searches through the street network, providing some insight into the internals of the routing algorithms that are not otherwise visible. diff --git a/doc/user/Getting-OTP.md b/doc/user/Getting-OTP.md index cfb0102c2a3..92f1e7298fc 100644 --- a/doc/user/Getting-OTP.md +++ b/doc/user/Getting-OTP.md @@ -64,13 +64,13 @@ OTP. If all goes well you should see a success message like the following: [INFO] ------------------------------------------------------------------------ ``` -This build process should produce a JAR file called `otp-x.y.z-shaded.jar` in the `target/` -directory which contains all the compiled OTP classes and their dependencies (the external libraries -they use). The shell script called 'otp' in the root of the cloned repository will start the main -class of that JAR file under a Java virtual machine, so after the Maven build completes you should -be able to run `./otp --help` and see an OTP help message including command line options. Due to the -way Maven works, this script is not executable by default, so you will need to do `chmod u+x ./otp` -before you run it to mark it as executable. +This build process should produce a JAR file called `otp-x.y.z-shaded.jar` in the +`application/target/` directory which contains all the compiled OTP classes and their dependencies +(the external libraries they use). The shell script called 'otp' in the root of the cloned repository +will start the main class of that JAR file under a Java virtual machine, so after the Maven build +completes you should be able to run `./otp --help` and see an OTP help message including command line +options. Due to the way Maven works, this script is not executable by default, so you will need to do +`chmod u+x ./otp` before you run it to mark it as executable. The words "clean package" are the build steps you want to run. You're telling maven to clean up any extraneous junk in the directory, then perform all the build steps, including compilation, up to and diff --git a/doc/user/Localization.md b/doc/user/Localization.md deleted file mode 100644 index 75d21e96ce4..00000000000 --- a/doc/user/Localization.md +++ /dev/null @@ -1,229 +0,0 @@ -# Localization - -NOTE: This documentation pertains to the client included in the main OTP repository. THIS BUILT-IN -OTP CLIENT IS PROVIDED FOR TEST AND DEBUGGING PURPOSES. IT IS NOT MEANT FOR PRODUCTION USE. - -This page contains instructions for both developers and translators on how to make the OTP interface -usable by people who speak different languages. Developers will need to take certain steps to mark -translatable strings within the source code. Translators will need to edit specific files within the -project to create or revise the translation for their language. - -In OTP we use gettext for localization, for the following reasons: - -- [Plural suport](http://pology.nedohodnik.net/doc/user/en_US/ch-poformat.html#sec-poplurals) -- [Context support](http://pology.nedohodnik.net/doc/user/en_US/ch-poformat.html#sec-poautocmnt) -- Automatic extraction of translatable strings from source code -- [Translator comments](http://pology.nedohodnik.net/doc/user/en_US/ch-poformat.html#sec-poautocmnt) - support -- Source references (we can see where each translated string is used in the source code) - -In the Javascript UI the [i18next](http://i18next.com) library is used. - -Three types of files are used in the OTP localization process: - -- The `.pot` file is the message template. It is a starting point for creating new `.po` files. -- `.po` files are created and edited by translators based on the `.pot` file. -- `.json` files are generated from the `.po` files for each language. -- `.js` files are localization configuration files which specify units and time/date formats. - -Only the `.po` and `.js` files are directly edited. The `.pot` file is created from an automated -analysis of annotated source code. The `.json` files are also automatically generated as an easy way -for the Javascript UI to consume the contents of the `.po` files. - -All translation files are in the directory `/src/client/i18n`. - -## For Software Developers: Adding New Strings - -When you add a string to Javascript source that will be seen by the end user, wherever that string -is referenced you should surround it with a call to a special function. The name of the function -depends on what kind of string it is: - -- basic string: `_tr('string', parameters)` -- basic string with context: `ngettext('context', 'string')` -- string with plural: `ngettext('singular', 'plural', quantity)` -- string with plural and context: `npgettext('context', 'singular', 'plural', quantity)` - -For more detail, -see [Sprintf parameters](http://www.diveintojavascript.com/projects/javascript-sprintf). - -A "context" is any string (preferably short and without whitespace) that is used to disambiguate the -translation of the main string. It is used when developers get input from translators that some -string should be translated in different ways in different parts of the program. Each of those -distinct places will be assigned a different context string. - -When you add strings to the source code, if you think that translators might not understand how the -string is used or what parameters it requires, add translator comments like this: - -```javascript -//TRANSLATORS: Start: location at [time date] (Used in print itinerary -//when do you start your trip) -html += '

' + _tr('Start: %s at %s', this.getStartLocationStr(), this.getStartTimeStr()) + '

'; -``` - -Translator comments must always start with `TRANSLATORS:` and must be in the line immediately before -translated string. Otherwise they won't be extracted together with the string. - -### Examples: - -#### Basic translated string - -```javascript -//TRANSLATORS: Board Public transit route name (agency name -//Stop ID ) start time -html += '
  • ' + _tr('Board') + ': ' + leg.from.name + ' (' + leg.from.stopId.agencyId + ' Stop ID #' + - -//With named sprintf parameters (our preferred option) - -//TRANSLATORS: Start: location at [time date] (Used in print itinerary -//when do you start your trip) -html += '

    ' + _tr('Start: %(location)s at %(time_date)s', { - 'location': this.getStartLocationStr(), - 'time_date': this.getStartTimeStr() -}) + '

    '; - -//With positional sprintf parameters (to be avoided because word order changes between languages) -html += '

    ' + _tr('End: %1$s at %2$s', this.getEndLocationStr(), this.getEndTimeStr()) + '

    '; -``` - -#### Normal string with context - -```javascript - if (leg.headsign) html += pgettext("bus_direction", " to ") + leg.headsign; - -//same string could be different translation -//TRANSLATORS: [distance] to [name of destination] -html += " " + otp.util.Itin.distanceString(leg.distance) + pgettext("direction", " to ") + leg.to.name; - -``` - -#### Plural strings - -```javascript -//TRANSLATORS: widget title -this.setTitle(ngettext("%d Itinerary Returned", "%d Itineraries Returned", this.itineraries.length)); -``` - -If you add new strings to the source code, it is good practice to also update the translation -template and the translations but it is not mandatory (these can be updated later). It is also -recommended to include "i18n string change" in the commit message. - -Updating translations ---------------------- -Translations are updated with the help of [Babel](http://babel.pocoo.org/) -and [i18next-conv](https://github.com/jamuhl/i18next-gettext-converter) (xgettext doesn't yet have -great Javascript support). - -Babel is used to extract strings from the Javascript source code into the shared `.POT` translation -template, and also for updating the existing `.PO` language translations when new strings are -introduced in the template. i18next-conv is used to convert the `.PO` translation files for the -individual languages to `.json` files which are used by the Javascript translation library. - -### Installing Babel - -You can install it from your operating system's package repository (if available) or you can -use [virtualenv](http://simononsoftware.com/virtualenv-tutorial/). - -1. Install virtualenv (This depends on your operating system) -2. Create virtualenv with name .venv in directory where src and other files resides (Root - OpenTripPlanner directory). `virtualenv2 .venv`(python 2) or `python3 -m venv .venv` (python 3) -3. Use virtualenv `source .venv/bin/activate` -4. Install babel `pip install babel` - -If you didn't install babel from virtualenv in root OpenTripPlanner directory you have to add path -to babel in Makefile. change `PYBABEL` variable to path to pybabel. - -### Installing i18next-conv - -i18next-conv requires [nodejs](http://nodejs.org/). - -Once you have NodeJS installed, use `npm install i18next-conv` to install i18next-conv in the same -directory where you created virtualenv. - -### Updating the `.pot` Template - -In the root of the OTP repo, run `make`. The commands in the `Makefile` will extract the -translatable strings from the Javascript files and update the translation template `messages.pot`, -as well as the `.po` translation files for all the different languages. - -Once this is done, you can translate the new strings in the `.po` files. After saving the -updated `.po` file, run -`make update_js` to transform to PO files into `.json`, which is used at runtime by the Javascript -translation library. After you rebuild OTP, all new strings should be visible in the UI. - -## For Translators: Creating New Translations - -The following can get a bit technical. If you want to do a translation but don't want to / know how -to install all this software, post to the [Gitter chat room](https://gitter.im/opentripplanner/OpenTripPlanner) -stating what language you want to translate, and someone will make you a corresponding `.po` file. - -### Creating a New Translation File - -New `.po` files are created from the `.pot` template with the help of `msginit`, which is run like -this: -`msginit init -l -i messages.pot -o .po`, where `` is a culture code. New `.po`files -can also be created with the help of `Poedit`. All translation files should be placed in the -directory `/src/client/i18n`. - -Please use the ISO language code as the culture code (e.g. `fr.po` for French). We will append -country codes in the following limited circumstances: - -- British versus US English (`en_GB.po` and `en_US.po`) -- Brazilian Portuguese `pt_BR.po`, as opposed to `pt.po` for European Portuguese -- Chinese: `zh_TW.po` for traditional characters as used in e.g. Taiwan and Hong Kong, - and `zh_CN.po` for simplified characters as used in mainland China, Singapore, etc. - -These conventions are based on -the [Launchpad Translation](https://help.launchpad.net/Translations/YourProject/ImportingTranslations) -page. - -In Linux you can see the culture codes for all the locales you have installed with the -command `locale -a`. A list of culture codes is also -availible [here](http://download1.parallels.com/SiteBuilder/Windows/docs/3.2/en_US/sitebulder-3.2-win-sdk-localization-pack-creation-guide/30801.htm) -. - -### Performing the Translation - -#### Configuration - -Copy the locale configuration script `English.js` from `/src/client/js/otp/locale` -to `YourLanguage.js` and customize it to your language. Change the name, units, locale_short and -datepicker_locale_short values. Translate infoWidgets and localize the time/date formats. - -Then take the following steps: - -- Add the culture code to the `LANGS` variable in the Makefile` -- Add the new `YourLanguage.js` to the locales variable in `/src/client/js/otp/config.js` -- Add a new datepicker translation to `/src/client/js/lib/jquery-ui/i18n` -- Load the new datepicker translation and `YourLanguage.js` in `/src/client/index.html` - -#### Translating Strings - -For translating the strings themselves, you can use any program that supports gettext files. You can -in theory use any text editor, but programs or plugins purpose-built for translating are -recommended. Most of them support checking parameter correctness, translation memory, web -translating services etc. to make the task easier. - -Here are some such programs (all free and open source): - -- [Poedit](http://poedit.net/) For Linux, Windows, and Mac. Use a version newer then 1.5. This is - the recommended choice for getting started with localization. It supports translation memory and - file context. -- [Web Poedit](https://localise.biz/free/poedit) Usable from within a web browser, you don't have to - install or register -- [Gted](http://www.gted.org/) A plugin for the Eclipse IDE. -- [Lokalize](http://userbase.kde.org/Lokalize) Runs under KDE on Linux, has some Windows support. - Supports translation memory and file context. -- [Virtaal](http://virtaal.translatehouse.org/index.html) For Linux, Windows, and beta for Mac. - Supports Google and Microsoft web translation and other translation memory services. - -All these programs support setting a string to "fuzzy", marking that it needs review etc. in case -you translate something but aren't sure of it's correctness. Sometimes those flags are set -automatically if the original string was changed and translators must check if the translation is -still correct. - -#### Caveats - -Be careful when translating that the translated strings have the same format as the original. If -spaces appear at the start or end of the strings, they must also appear in the translation. The -order of unnamed (positional) parameters may change depending on the target language. You can also -leave parameter out of the translation if it is irrelevant in the target language. diff --git a/doc/user/RouterConfiguration.md b/doc/user/RouterConfiguration.md index 711eca3fb87..766ad0de4ef 100644 --- a/doc/user/RouterConfiguration.md +++ b/doc/user/RouterConfiguration.md @@ -14,7 +14,7 @@ These options can be applied by the OTP server without rebuilding the graph. Certain settings can be provided on the command line, when starting OpenTripPlanner. See the `CommandLineParameters` class -for [a full list of arguments](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/standalone/config/CommandLineParameters.java) +for [a full list of arguments](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/main/java/org/opentripplanner/standalone/config/CommandLineParameters.java) . ## Routing defaults diff --git a/doc/user/Troubleshooting-Routing.md b/doc/user/Troubleshooting-Routing.md index 4e237baa9fc..cd7eaa04c88 100644 --- a/doc/user/Troubleshooting-Routing.md +++ b/doc/user/Troubleshooting-Routing.md @@ -148,7 +148,7 @@ props.setProperties("surface=mud", StreetTraversalPermission.ALL, 1.5, 1.5, true ``` The Javadoc -of [`OSMSpecifier.java`](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/graph_builder/module/osm/OSMSpecifier.java) +of [`OSMSpecifier.java`](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/main/java/org/opentripplanner/osm/wayproperty/specifier/OsmSpecifier.java) contains the precise documentation about the syntax of the matchers. There are a lot of rules for which tags results in a specific safety score so it's not easy to get diff --git a/doc/user/apis/GraphQL-Tutorial.md b/doc/user/apis/GraphQL-Tutorial.md index 5c4b59e864e..41695de304a 100644 --- a/doc/user/apis/GraphQL-Tutorial.md +++ b/doc/user/apis/GraphQL-Tutorial.md @@ -138,4 +138,4 @@ Most people want to get routing results out of OTP, so lets see the query for th Again, please use the autocomplete and documentation viewers to figure out what each input parameter and property means. -More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/test/resources/org/opentripplanner/apis/gtfs/queries). \ No newline at end of file +More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/application/src/test/resources/org/opentripplanner/apis/gtfs/queries). \ No newline at end of file diff --git a/doc/user/sandbox/GoogleCloudStorage.md b/doc/user/sandbox/GoogleCloudStorage.md index 2fdc688a247..4876857b727 100644 --- a/doc/user/sandbox/GoogleCloudStorage.md +++ b/doc/user/sandbox/GoogleCloudStorage.md @@ -14,7 +14,7 @@ To enable this turn on the feature `GoogleCloudStorage`. OTP can load or store artifacts from one or more Google Cloud Storge locations. Each artifact must be configured in the _build-config.json_: -See [`BuildConfig`](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/main/java/org/opentripplanner/standalone/config/BuildConfig.java) +See [`BuildConfig`](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/main/java/org/opentripplanner/standalone/config/BuildConfig.java) on how to configure artifacts. Example (build-config.json): diff --git a/doc/user/sandbox/transferanalyzer.md b/doc/user/sandbox/transferanalyzer.md index edc1a2579ea..d1dfabe10b2 100644 --- a/doc/user/sandbox/transferanalyzer.md +++ b/doc/user/sandbox/transferanalyzer.md @@ -17,5 +17,5 @@ generates lists of both unusually long and unroutable transfers. These lists can to improve the quality of OSM data for transfer purposes. See javadoc in -[DirectTransferAnalyzer](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/src/ext/java/org/opentripplanner/ext/transferanalyzer/DirectTransferAnalyzer.java) +[DirectTransferAnalyzer](https://github.com/opentripplanner/OpenTripPlanner/blob/dev-2.x/application/src/ext/java/org/opentripplanner/ext/transferanalyzer/DirectTransferAnalyzer.java) class \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 1364be7be1f..dd060c3ffd1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -95,7 +95,6 @@ nav: - "Logging": "Logging.md" - Development: - "Developers' Guide": 'Developers-Guide.md' - - Localization: 'Localization.md' - Bibliography: 'Bibliography.md' - Sandbox Development: 'SandboxExtension.md' - Release Checklist: 'ReleaseChecklist.md'