Skip to content

Latest commit

 

History

History
164 lines (128 loc) · 7.92 KB

README.md

File metadata and controls

164 lines (128 loc) · 7.92 KB

Language (I18N) Extension Specification

This document is the Language (I18N) Extension to the SpatioTemporal Asset Catalog (STAC) specification, which explains fields and recommendations around making multi-lingual STAC catalogs available.

The focus of this extension is to make multi-lingual static STAC catalogs available. There's also a dedicated language extension for STAC APIs. So there's a STAC Language extension and a STAC API Langauge extension.

Fields for Catalogs, Collections and Item Properties

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
language Language Object REQUIRED. The language of the document.
languages [Language Object] Other languages the document is available in. This list MUST NOT contain the language of the document.

Note: OGC API - Records defines an additional field resourceLanguages to specify the list of languages the resource (assets) being described by the Record (Item, Catalog, or Collection) is available in. For details see list of languages for assets.

Language Object

Each Language Object describes an individual language. Implementors may add additional properties for their usecases (e.g. for formatting numbers or dates and times).

Field Name Type Description
code string REQUIRED. This MUST be the valid Language-Tag for the language as specified in RFC 5646.
name string The name of the language in the language itself (e.g. "Deutsch" for German). This MUST NOT be translated.
alternate string The name of the language in another well-understood language, usually English (e.g. "German" for German).
dir string The direction for text in this language. Either ltr (left-to-right) or rtl (right-to-left). Defaults to ltr.

alternate

It is a good practice to provide language names in two languages so that they can be understood both by users that speak and don't speak the language. The name is always in the language of the language itself and caters for users that speak this language. alternate caters for users that don't speak the language. It is often English, but could be something else, e.g., it could be in the language of the document itself.

Fields for Links and Assets

The fields in the table below can be used in these parts of STAC documents:

  • Catalogs
  • Collections
  • Item Properties (incl. Summaries in Collections)
  • Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
  • Links
Field Name Type Description
hreflang string The language to be expected for the href in the link or asset. The language MUST BE a valid Language-Tag as specified in RFC 5646.

Best practices

  • The alternate relation type should be used to provide links to the same resource, but in other languages. Be aware that alternative representations can also point to alternative media types, e.g. an HTML representation of the JSON files. So to get all links to (Geo)JSON files for the various languages, you also need to check the media type.
  • Other links to STAC documents (e.g. for relation types item, child, parent, root) should only be provided in the language present in the current document.
  • STAC Assets should always be provided in all languages.
  • The STAC files for the individual languages should be provided in separate subfolders, but the default language can be provided in the parent of the sub-folders (for an example please see the examples folder).

Relation to other specifications

The specification aims for alignment with

More specifically, the language and languages properties are aligned with OGC API - Records. The hreflang property is defined in RFC 8288 and various OGC APIs, e.g. Features, Records and Common.

List of languages for assets

OGC API - Records defines an additional field resourceLanguages to specify the list of languages the resource (in STAC: Assets) being described by the Record (in STAC: Item, Catalog, or Collection) is available in. The field name might be confusing to STAC users as the term "resources" in STAC would be "assets". In many cases, assets are not translatable in STAC (e.g. raster imagery), but you can still get a list of language codes by reading the hreflang properties for all assets.

Examples in JavaScript:

let assetLanguages = new Set();
Object.values(stac.assets)
  .filter(asset => typeof asset.hreflang === 'string')
  .forEach(asset => assetLanguages.add(asset.hreflang));
let assetLanguages = [];
for(key in stac.assets) {
  let asset = stac.assets[key]
  if (typeof asset.hreflang === 'string' && !assetLanguages.includes(asset.hreflang)) {
    assetLanguages.push(asset.hreflang);
  }
}

Implementations

The following client and/or server software implement this extension:

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples