多语言支持

pyGeoapi是语言感知的，如果在pyGeoapi的配置中定义了多种语言，则可以处理这些语言(请参见 maintainer guide )。如果配置，提供程序还可以处理多种语言。这些语言甚至可能与pygeapi支持的语言不同。开箱即用的Pygeapi会“说”英语。系统消息和异常始终仅为英文。

以下各节提供如何在pygeapi中使用和设置语言的更多信息。

最终用户指南

对于HTML和JSON(-LD)格式，有两种方式可以影响pygeapi返回的结果的语言：

  1. 在请求的pyGeoapi URL之后，追加一个 lang=<code> 查询参数，其中 <code> 应由众所周知的语言代码替换。这可以是ISO 639-1代码(例如 de for German), optionally accompanied by an ISO 3166-1 alpha-2 country code (e.g. de-CH for Swiss-German). Please refer to this W3C article 有关更多信息或此信息 list of language codes 查看更多示例。另一种选择是发送带有质量权重的复杂定义(例如 de-CH, de;q=0.9, en;q=0.8, fr;q=0.7, *;q=0.5 )。然后，pygeapi将计算出与所请求的语言最匹配的语言。

    例如，要使用加拿大法语查看pyGeoapi登录页面，您可以使用以下URL：

    https://demo.pygeoapi.io/master?lang=fr-CA

  2. 或者，您可以将 Accept-Language 请求的pyGeoapi URL的HTTP标头。语言标记，这些标记对 lang 查询参数对此标头值也有效。请注意，如果您的客户端应用程序(例如浏览器)配置为使用某种语言，它很可能会默认设置此标头，因此返回的响应应转换为您的客户端应用程序的语言。如果您不需要这样做，您可以更改客户端应用程序的语言或将 lang 参数设置为URL，该参数将重写 Accept-Language 标题。

注意事项

  • 如果pygeapi找不到与请求的语言很好的匹配，则以默认语言(主要是美国英语)返回响应。默认语言是 第一 PyGeoapi的服务器配置YAML中定义的语言(请参见 maintainer guide )。

  • 即使是比利亚皮 本身 支持请求的语言，则提供程序插件可能不支持该特定语言，甚至可能根本不支持任何语言。在这种情况下，提供程序将使用其自己的“未知”语言进行回复，该语言可能与 Content-Language HTTP响应头。

  • 应由提供程序的创建者在提供程序配置中正确定义至少1种受支持的语言，如 developer guide 。这将确保 Content-Language HTTP响应头始终设置正确。

  • 如果pygeapi找到与请求的语言匹配的语言，则响应将包括 Content-Language HTTP标头，设置为最佳匹配的服务器语言代码。这是大多数pyGeoapi请求的默认行为。但是，请注意，某些响应(例如异常)始终具有 Content-Language: en-US 标头，而不考虑请求的语言。

  • 对于由 提供商 ，即 Content-Language 如果提供程序不支持语言，则HTTP标头将设置为最佳匹配的提供程序语言或最佳匹配的pyGeoapi服务器语言。

  • 如果提供程序支持请求的语言，但pyGeoapi支持 not 支持相同语言，则 Content-Language 标头将同时包含提供程序语言 and 最佳匹配的pyGeoapi服务器语言。

  • 请注意， Content-Language 仅HTTP响应头 指示目标受众的语言 。这并不一定意味着内容实际上是用该特定语言编写的。

维护人员指南

每个pygeapi实例应至少支持一种语言。在服务器配置中，必须有 language 或者是 languages (请注意 s )财产。该属性可以分别设置为单语言标记或标记列表。

如果您希望设置多语言pyGeoapi实例，则必须向服务器配置YAML文件添加一种以上的语言(即 pygeoapi-config.yml )。首先，您必须将支持的语言标记/代码添加为列表。例如，如果您希望支持美国英语和加拿大法语，您可以执行以下操作：

server:
    bind: ...
    url: ...
    mimetype: ...
    encoding: ...
    languages:
        - en-US
        - fr-CA

接下来，您必须为配置的语言提供翻译。这包括3个步骤：

  1. Add translations for configurable text values 在PyGeoapi构型中；

  2. 验证是否有针对所配置语言的任何JJIA2 HTML模板翻译；

  3. 确保您需要的提供程序插件也可以处理此语言，如果您有能力这样做的话。请参阅 developer guide 了解更多详细信息。

注意事项

  • 这个 第一 您在配置中定义的语言确定默认语言，即，如果没有请求其他语言或找不到与请求的语言最匹配的语言，pyGeoapi将使用的语言。

  • 这是不可能的 禁用 PyGeoapi中的语言支持。该功能始终处于打开状态，并且 Content-Language 始终设置HTTP响应头。如果结果应该只有一种语言，那么您只需在pyGeoapi配置中设置该语言即可。

  • 从提供程序返回的结果可能使用与pygeapi自己的服务器语言不同的语言。“原始”请求的语言总是传递给提供程序，即使pyGeoapi本身不支持它。有关更多信息，请参阅 end user guide 以及 developer guide 。

添加可配置文本值的翻译

对于pygeapi的服务器配置中有意义的大多数文本值，您可以添加翻译。考虑一下 metadata 以节为例。纯英语版本如下所示：

metadata:
    identification:
        title: pygeoapi default instance
        description: pygeoapi provides an API to geospatial data
        keywords:
            - geospatial
            - data
            - api

如果希望以英语和法语提供这些文本值，可以使用以下语言结构：

metadata:
    identification:
        title:
            en: pygeoapi default instance
            fr: instance par défaut de pygeoapi
        description:
            en: pygeoapi provides an API to geospatial data
            fr: pygeoapi fournit une API aux données géospatiales
        keywords:
            en:
                - geospatial
                - data
                - api
            fr:
                - géospatiale
                - données
                - api

换句话说：每个纯文本值都应该用字典替换，其中语言代码是关键字，翻译后的文本代表匹配值。对于列表，这也可以应用(请参见 keywords 上面的示例)，只要您将整个列表嵌套在一个语言键下，而不是每个列表项。

类似的概念也可以应用于 title-field 集合配置中提供程序的属性。如果数据集包含多个列，每个列都以特定语言表示标题元素，则可以相应地配置标题字段。

providers:
  - type: feature
    name: GeoJSON
    data: tests/data/ne_110m_lakes.geojson
    title_field:
      en: name_eng
      fr: nom_fre
      de: name_deu

请注意，上面的示例使用通用语言标记，但如果需要，您也可以提供更多本地化标记(带有国家代码)。pygeapi应该总是能够找到与所请求的语言最匹配的语言，即如果用户想要瑞士语-法语 (fr-CH )但是Pygeapi只能找到 fr 标记，则将返回这些值。但是，如果一个 fr-CH 标记，则将返回该值，而不是 fr 价值。

警告

只有当结构中的所有语言标记(键)都是有效的区域设置时，语言结构才会被翻译。

待处理

添加关于HTML模板的文档。

翻译指南

使用Babel翻译系统翻译PYGeoapi模板中的硬编码字符串。

默认情况下，pygeapi将转换文件存储在 locale 位于源代码存储库的根目录中。该值可以在pygeapi配置中用 server.locale_dir 指令。

翻译人员可以按照以下步骤为翻译准备环境。

  1. 从最新代码中提取要转换的密钥。这些密钥在 .pot 文件。请注意， .pot 文件不存储在版本控制中，而是作为用于更新的中间文件 locale/*/LC_MESSAGES/messages.po 文件：

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

  2. 更新现有的.po语言文件：

    pybabel update -d locale -l fr -i locale/messages.pot

  3. 打开相关的.po文件并贡献您的翻译。然后编译应用程序要使用的.mo文件：

    pybabel compile -d locale -l fr

在JJJA模板中，通过将密钥包装在以下内容中，可以准备对其进行转换：

{% trans %}Key{% endtrans %}

开发人员指南

如果您是一名希望创建“会说”某种语言的pyGeoapi提供程序插件的开发人员，那么您必须自己完全实现这一点。不用说，如果您的提供商依赖于某些后端，那么只有在后端也可以用另一种语言查询时，实现语言支持才有意义。

您可以随心所欲地设置语言支持，但您必须完成以下几个步骤：

  1. 您必须在提供程序配置YAML中定义支持的语言。这可以用类似于 languages pygeapi本身的配置，如 maintainer guide 上面的部分。例如，支持英语和法语的TinyDB记录提供程序可以设置为：

    my-records:
    type: collection
    ..
    providers:
        - type: record
          name: TinyDBCatalogue
          data: ..
          languages:
              - en
              - fr

  2. 如果您的提供程序实现了任何 query ， get 或 get_metadata 方法，并且您希望使它们能够识别语言，则可以添加隐式的 **kwargs 参数或显式 language=None 参数添加到方法签名。

用于具有语言感知的自定义提供程序的Python代码挡路示例 query 方法可能如下所示：

class MyCoolVectorDataProvider(BaseProvider):
"""My cool vector data provider"""

def __init__(self, provider_def):
    super().__init__(provider_def)

def query(self, offset=0, limit=10, resulttype='results', bbox=[],
          datetime_=None, properties=[], sortby=[], select_properties=[],
          skip_geometry=False, q=None, language=None):
    LOGGER.debug(f'Provider queried in {language.english_name} language')
    # Implement your logic here, returning JSON in the requested language

或者，您也可以使用 **kwargs 在 query 方法，并获取 language 值：

def query(self, **kwargs):
    LOGGER.debug(f"Provider locale set to: {kwargs.get('language')}")
    # Implement your logic here, returning JSON in the requested language

这就是所需的全部内容。pyGeoapi API类将确保正确的HTTP Content-Language 在响应对象上设置标头。

注意事项

  • 如果您的提供商实现了上述任何 query ， get 和 get_metadata 方法，它 must 添加 **kwargs 或 language=None 参数，即使它不需要使用Language参数。

  • 与pyGeoapi服务器配置相反，添加一个 language 或 languages (两者都受支持)提供程序定义的属性为 not 必填项，可以省略。在这种情况下，传入的 language 参数语言感知的提供程序方法 (query ， get 等)将设置为 None 。这将导致以下行为：

    • 从提供程序返回的HTML响应将具有 Content-Language 标头设置为最佳匹配的pyGeoapi服务器语言。

    • 从提供程序返回的JSON(-ld)响应将 not 祝你有一个 Content-Language 标题(如果) language 是 None 。

  • 如果提供程序支持请求的语言，则传入的 language 将设置为最佳匹配 Babel Locale instance 。请注意，如果找不到合适的匹配项，则这可能是提供程序的默认语言。无论输出格式如何，提供程序返回的API响应都将始终包含最佳匹配 Content-Language 如果定义了一种或多种支持的提供程序语言，则返回标头。

  • 有关构建插件的一般信息，请访问 自定义pygeoapi:插件 佩奇。