Skip to content

Internationalization (i18n)

Every class in a pedotri classification can carry localized display names. The same machinery resolves the localized name of the classification itself.

Locale resolution

pedotri.classify(..., locale=<tag>) looks up the requested locale in three stages:

  1. Exact match ("fr-FR").
  2. Progressively strip regional/script subtags ("fr-FR" → "fr").
  3. Fall back to "en".
  4. Fall back to the class key (always present).

This means a classification can ship with only an English name table and still work for users requesting other locales — they'll see the class keys.

Reading localized names

import pedotri

pedotri.classify(13, 50, "USDA", locale="fr")   # 'argile'
pedotri.classify(13, 50, "USDA", locale="ru")   # 'глина'
pedotri.classify(13, 50, "USDA", locale="ja")   # 'clay' — falls back to en
pedotri.classify(13, 50, "USDA")                # 'clay' — returns the key, never a localized name

To get the localized classification name (e.g. for a chart title):

c = pedotri.get_classification("KACHINSKY")
c.name("ru")   # 'Классификация Качинского'
c.name("en")   # 'Kachinsky classification'

Listing available locales

Classification.locales() returns the union of every locale declared anywhere in the classification (on the classification itself or on any class).

c = pedotri.get_classification("USDA")
sorted(c.locales())   # ['de', 'en', 'es', 'fr', 'pt', 'ru']

Default locale

Each classification declares a default_locale in TOML. This is the locale used:

  • in the detailed=True return path's ClassifyResult.name field when no locale is passed;
  • in the SVG / matplotlib / plotly diagram legend when no locale is passed.

For example, GEPPA ships with default_locale = "fr", so the diagram legend is in French by default; KACHINSKY defaults to "ru".

Adding a locale to a built-in

Override or extend a built-in classification's names by loading it, mutating, and re-registering:

import pedotri

usda = pedotri.get_classification("USDA")
usda.class_by_key("clay").names["it"] = "argilla"
usda.class_by_key("sand").names["it"] = "sabbia"
pedotri.register_classification(usda, overwrite=True)

pedotri.classify(13, 50, "USDA", locale="it")   # 'argilla'

For a permanent contribution, open a pull request adding the locale to the TOML file under src/pedotri/_data/classifications/.

Authoring a multilingual classification

See the Custom classifications page for the full TOML schema. Class-level [class.names] and classification-level [meta.names] tables both accept arbitrary IETF locale tags as keys.