This module defines methods and object to help the internationalization of metadata for climate indicators computed by xclim. Go to Adding translated metadata to see how to use this feature.

All the methods and objects in this module use localization data given in json files. These files are expected to be defined as in this example for french:

    "attrs_mapping": {
        "modifiers": ["", "f", "mpl", "fpl"],
        "YS": ["annuel", "annuelle", "annuels", "annuelles"],
        "AS-*": ["annuel", "annuelle", "annuels", "annuelles"],
        # ... and so on for other frequent parameters translation...
    "DTRVAR": {
        "long_name": "Variabilité de l'amplitude de la température diurne",
        "description": "Variabilité {freq:f} de l'amplitude de la température diurne (définie comme la moyenne de la variation journalière de l'amplitude de température sur une période donnée)",
        "title": "Variation quotidienne absolue moyenne de l'amplitude de la température diurne",
        "comment": "",
        "abstract": "La valeur absolue de la moyenne de l'amplitude de la température diurne.",
    # ... and so on for other indicators...

Indicators are named by subclass identifier, the same as in the indicator registry (xclim.core.indicators.registry), but which can differ from the callable name. In this case, the indicator is called through atmos.daily_temperature_range_variability, but its identifier is DTRVAR. Use the ind.__class__.__name__ accessor to get its registry name.

Here, the usual parameter passed to the formatting of “description” is “freq” and is usually translated from “YS” to “annual”. However, in french and in this sentence, the feminine form should be used, so the “f” modifier is added by the translator so that the formatting function knows which translation to use. Acceptable entries for the mappings are limited to what is already defined in xclim.core.indicators.utils.default_formatter.

For user-provided internationalization dictionaries, only the “attrs_mapping” and its “modifiers” key are mandatory, all other entries (translations of frequent parameters and all indicator entries) are optional. For xclim-provided translations (for now only french), all indicators must have en entry and the “attrs_mapping” entries must match exactly the default formatter. Those default translations are found in the xclim/locales folder.

xclim.core.locales.TRANSLATABLE_ATTRS = ['long_name', 'description', 'comment', 'title', 'abstract', 'keywords']

List of attributes to consider translatable when generating locale dictionaries.

exception xclim.core.locales.UnavailableLocaleError(locale)[source]

Bases: ValueError

Error raised when a locale is requested but doesn’t exist.

xclim.core.locales.generate_local_dict(locale: str, init_english: bool = False) dict[source]

Generate a dictionary with keys for each indicator and translatable attributes.

  • locale (str) – Locale in the IETF format

  • init_english (bool) – If True, fills the initial dictionary with the english versions of the attributes. Defaults to False.

xclim.core.locales.get_local_attrs(indicator: str | Sequence[str], *locales: str | Sequence[str] | tuple[str, dict], names: Sequence[str] | None = None, append_locale_name: bool = True) dict[source]

Get all attributes of an indicator in the requested locales.

  • indicator (str or sequence of strings) – Indicator’s class name, usually the same as in xc.core.indicator.registry. If multiple names are passed, the attrs from each indicator are merged, with the highest priority set to the first name.

  • locales (str or tuple of str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.

  • names (Optional[Sequence[str]]) – If given, only returns translations of attributes in this list.

  • append_locale_name (bool) – If True (default), append the language tag (as “{attr_name}_{locale}”) to the returned attributes.


ValueError – If append_locale_name is False and multiple locales are requested.


dict – All CF attributes available for given indicator and locales. Warns and returns an empty dict if none were available.

xclim.core.locales.get_local_dict(locale: str | Sequence[str] | tuple[str, dict]) tuple[str, dict][source]

Return all translated metadata for a given locale.


locale (str or sequence of str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.


UnavailableLocaleError – If the given locale is not available.


  • str – The best fitting locale string

  • dict – The available translations in this locale.

xclim.core.locales.get_local_formatter(locale: str | Sequence[str] | tuple[str, dict]) AttrFormatter[source]

Return an AttrFormatter instance for the given locale.


locale (str or tuple of str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.


List of loaded locales. Includes all loaded locales, no matter how complete the translations are.

xclim.core.locales.load_locale(locdata: str | Path | Mapping[str, dict], locale: str)[source]

Load translations from a json file into xclim.

  • locdata (str or dictionary) – Either a loaded locale dictionary or a path to a json file.

  • locale (str) – The locale name (IETF tag).

xclim.core.locales.read_locale_file(filename, module: str | None = None, encoding: str = 'UTF8') dict[source]

Read a locale file (.json) and return its dictionary.

  • filename (PathLike) – The file to read.

  • module (str, optional) – If module is a string, this module name is added to all identifiers translated in this file. Defaults to None, and no module name is added (as if the indicator was an official xclim indicator).

  • encoding (str) – The encoding to use when reading the file. Defaults to UTF-8, overriding python’s default mechanism which is machine dependent.