Multilingual support

[GeoSander]

Enables multilingual support for pygeoapi (core and plugins). Refer to issue #100 for discussion.

Work done

• Server-independent language check (from request l parameter or Accept-Language header)
• Make providers, processes and formatters language-aware
• Add translate functionality for JSON language structs based on the current language setting (best match)
• Support responses with Content-Language header
• Multilingual metadata in configuration
• Add documentation
• Handle hreflang in links in configuration

I've decided to push the last item to a next PR. This PR is already big enough...
The generation/processing of all API links should be done in a separate function, imho (see "Upcoming PRs" below).

What does it do?

Users can now append a l=fr parameter to a pygeoapi URL and pygeoapi will return the requested page in French (for example). If the user connects to pygeoapi using a browser where the language has been set to French, the requested page will automatically be rendered in French (without the l=fr parameter), because the browser sent an Accept-Language header along with the request. However, this can always be overridden again using the l query parameter.

Remarks

• This PR is quite large and mainly impacts the API core (and not so much the plugins). Most of the language support stuff revolves around the new l10n (localization) module, which turns the requested language (e.g. "fr", "fr-CH" or "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5" into a best matching Babel Locale object. These Locale objects integrate well with Jinja2 templates using the i18n extension;
• The only text that is translatable at this moment, are the text strings (names, titles, descriptions, etc.) in the server configuration. The pygeoapi-config.yaml now contains some example language structs for US English and Canadian French (more translations coming up);
• In order to efficiently pass on language settings, I decided to make all API method calls more consistent, so api.py has undergone quite a lot of refactoring. All methods that require Request object data are now decorated by the @pre_process function, which converts the incoming Flask/Starlette Request into a (newly introduced) APIRequest instance. This class processes headers and query parameters to extract the required properties for the API methods. This results in less boilerplate and cleaner API method signatures, while still being explicit;
• Developers of third-party providers and other plugins should add a requested_locale=None argument to the __init__ method of their plugin, and pass the requested_locale to the super().__init__() call as a second argument. This is all that needs to be done to make the plugin work again and to make it language-aware. However, it is up to the developer to implement the logic to query/process data and return it in the requested language. Please refer to the provided Sphinx documentation for more info.

Follow-ups

This PR provides the foundation to make pygeoapi language-aware. However, for full language support, there are still some things that need to be done.

Upcoming PRs should address:

• Links generated by pygeoapi: the links underneath each collection item (for example) should become language-aware, i.e. internal link URLs should be appended with a l=<language> query parameter if the current page also was requested using that parameter (note: the add_locale function in the l10n module can be used for that.
  Internal links should also set the hreflang property to the user-specified language. For external links, this only applies if the server speaks that language (hard to figure out).
• HTML templates: all hard-coded translatable strings in the templates need to be stored in separate files and processed by pybabel. so they can be managed by a translation tool (e.g. Transifex);
• The Jinja2 i18n extension needs to be configured and the HTML templates need to be modified so that Jinja2 and Babel/gettext can inject the translations;
• All core plugins (e.g. providers) are now language-aware, but the ones that can support multiple languages (i.e. the plugin backend supports it) should still implement functionality for it. The l10n module provides the necessary tools to do so;
• Other suggestions...?

Some useful links concerning Jinja2/Babel/Transifex:

• https://www.mattlayman.com/blog/2015/i18n/
• https://phrase.com/blog/posts/i18n-advantages-babel-python/#Integration_with_Jinja2_templates
• https://jinja.palletsprojects.com/en/2.11.x/templates/#i18n-in-templates

[GeoSander]

Note: build should actually work, but 1/2 failed because of:

[jodygarnett]

Note: build should actually work, but 1/2 failed because of:

You have reached your pull rate limit

I note that the GEOS and PostGIS projects are using osgeo docker repository https://repo.osgeo.org/#browse/search/docker for test images (no pull rate limit there).

[tomkralidis]

Closing in lieu of #664