Skip to content

Multilingual support

pygeoapi supports multilinguality at three levels:

  • In the pygeoapi configuration you can provide titles and abstracts of the service and collections in multiple languages.
  • A set of translatable text-strings which are translated and introduced as part of the JSON and HTML output formats. Translations are managed by the Babel framework
  • Column names/values in feature based datasets. If a dataset contains columns in multiple languages, pygeoapi will try to return data responses in the requested language

Note

Error messages are not translated, to facilitate copy-paste of the error into stackoverflow and GitHub issues.

Language negotiation is triggered by the HTTP Accept-Language header as sent by the client, and can always be overridden with the ?lang=fr url parameter.

Multilingual configuration

In the pygeoapi configuration you can indicate the languages supported by the instance. The first language is the default language. For most of the textual configuration properties you can provide a translation in alternative languages.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
lakes:
  type: collection
  title:
      en: Large Lakes
      fr: Grands Lacs
  description:
      en: lakes of the world, public domain
      fr: lacs du monde, domaine public
  keywords:
      en:
          - lakes
          - water bodies
      fr:
          - lacs
          - plans d'eau

Text strings within Jinja2 HTML templates

Most of the translatable text strings exist within the Jinja2 HTML templates. Text strings to be translated are placed in a trans tag, as follows:

1
<title>{% trans %}Page title{% endtrans %}</title>

Babel provides a utility which extracts all keys to be translated from the templates into a single .pot file. 

pybabel extract -F babel-mapping.ini -o locale/messages.pot ./


pybabel extract -F babel-mapping.ini -o locale/messages.pot ./

The resulting .pot file is used to create or update existing .po files, which exist for each language, containing the actual translations.

pybabel init -d locale -l it -i locale/messages.pot


pybabel init -d locale -l it -i locale/messages.pot

The .po files are stored in pygeoapi's source code repository on GitHub. You can create a Pull Request to add or update your favourite languages. .po files can also be added to translation software such as transifex.com.

Edit a .po file

Open a .po file from the locale folder in a text editor. Edit some values. Save the file and restart the service. Verify that the updated content is available. You can also try to add a new key to a template and translate it via the .po mechanism.

Annotating the language of data columns

pygeoapi includes a meachanism to influence the API responses based on the requested language. If your service operates with multilingual requirements, it may make sense to add textual columns in multiple languages. For example, in the pygeoapi configuration you can then indicate which column should be used as the title field, for which language.

Publish a multilingual dataset

For this workshop we have prepared a multilingual dataset of free wifi hotspots in Florence (workshop/exercises/data/free-wifi-florence.csv). Add the dataset to the pygeoapi configuration using the CSV provider. Add a title-field configuration with for each translated column the relevant language.

1
2
3
4
5
6
data: /data/free-wifi-florence.csv
id_field: id
title_field: 
  en: name-en
  it: name-it
  de: name-de

Test the configuration by navigating to the items page of the collection and switching the language by appending ?lang=it, ?lang=de to the URL.

Summary

Congratulations! You've customized pygeoapi to support multiple languages.