Locales

Back to top

SearXNG’s locale data

The variables RTL_LOCALES and LOCALE_NAMES are loaded from / see locales_initialize and update_locales.py.

Hint

Whenever the value of ADDITIONAL_TRANSLATIONS or LOCALE_BEST_MATCH is modified, the needs to be rebuild:

./manage data.locales

SearXNG’s locale codes

List of SearXNG’s locale codes used for the search language/region.

Hint

Don’t modify this file, this file is generated by:

./manage data.traits

searx.sxng_locales.sxng_locales : A list of five-digit tuples:

0. SearXNG’s internal locale tag (a language or region tag)
1. Name of the language ([`babel.core.Locale.get_language_name`](https://babel.readthedocs.io/en/latest/api/core.html#babel.core.Locale.get_language_name))
2. For region tags the name of the region ([`babel.core.Locale.get_territory_name`](https://babel.readthedocs.io/en/latest/api/core.html#babel.core.Locale.get_territory_name)).
   Empty string for language tags.
3. English language name (from [`babel.core.Locale.english_name`](https://babel.readthedocs.io/en/latest/api/core.html#babel.core.Locale.english_name))
4. Unicode flag (emoji) that fits to SearXNG’s internal region tag. Languages
   are represented by a globe (🌐)

```
('en',    'English', '',              'English', '🌐'),
('en-CA', 'English', 'Canada',        'English', '🇨🇦'),
('en-US', 'English', 'United States', 'English', '🇺🇸'),
..
('fr',    'Français', '',             'French',  '🌐'),
('fr-BE', 'Français', 'Belgique',     'French',  '🇧🇪'),
('fr-CA', 'Français', 'Canada',       'French',  '🇨🇦'),
```

SearXNG’s locale implementations

searx.locales.LOCALE_NAMES: dict[str, str] : Mapping of locales and their description. Locales e.g. ‘fr’ or ‘pt-BR’ (see locales_initialize).

searx.locales.RTL_LOCALES: set[str] = {'ar', 'fa-IR', 'he'} : List of Right-To-Left locales e.g. ‘he’ or ‘fa-IR’ (see locales_initialize).

searx.locales.ADDITIONAL_TRANSLATIONS = {'dv': 'ދިވެހި (Dhivehi)', 'oc': 'Occitan', 'pap': 'Papiamento', 'szl': 'Ślōnski (Silesian)'} : Additional languages SearXNG has translations for but not supported by python-babel (see locales_initialize).

searx.locales.LOCALE_BEST_MATCH = {'dv': 'si', 'nl-BE': 'nl', 'oc': 'fr-FR', 'pap': 'pt-BR', 'szl': 'pl', 'zh-HK': 'zh-Hant-TW'} : Map a locale we do not have a translations for to a locale we have a translation for. By example: use Taiwan version of the translation for Hong Kong.

searx.locales.get_translations()[source] : Monkey patch of flask_babel.get_translations

searx.locales.get_translation_locales() → list[str][source] : Returns the list of translation locales (underscore). The list is generated from the translation folders in

searx.locales.locales_initialize()[source] : Initialize locales environment of the SearXNG session.

- monkey patch [`flask_babel.get_translations`](https://python-babel.github.io/flask-babel/index.html#flask_babel.get_translations) by [`get_translations`](#searx.locales.get_translations)
- init global names [`LOCALE_NAMES`](#searx.locales.LOCALE_NAMES), [`RTL_LOCALES`](#searx.locales.RTL_LOCALES)

searx.locales.region_tag(locale: Locale) → str[source] : Returns SearXNG’s region tag from the locale (e.g. zh-TW , en-US).

searx.locales.language_tag(locale: Locale) → str[source] : Returns SearXNG’s language tag from the locale and if exits, the tag includes the script name (e.g. en, zh_Hant).

searx.locales.get_locale(locale_tag: str) → Locale | None[source] : Returns a babel.Locale object parsed from argument locale_tag

searx.locales.get_official_locales(territory: str, languages: list[str] | None = None, regional: bool = False, de_facto: bool = True) → set[Locale][source] : Returns a list of babel.Locale with languages from babel.languages.get_official_languages.

Parameters:
:   - **territory** – The territory (country or region) code.
    - **languages** – A list of language codes the languages from
      [`babel.languages.get_official_languages`](https://babel.readthedocs.io/en/latest/api/languages.html#babel.languages.get_official_languages) should be in
      (intersection). If this argument is `None`, all official languages in
      this territory are used.
    - **regional** – If the regional flag is set, then languages which are
      regionally official are also returned.
    - **de\_facto** – If the de\_facto flag is set to False, then languages
      which are “de facto” official are not returned.

searx.locales.get_engine_locale(searxng_locale: str, engine_locales: dict[str, str], default: str | None = None) → str | None[source] : Return engine’s language (aka locale) string that best fits to argument searxng_locale.

Argument `engine_locales` is a python dict that maps *SearXNG locales* to
corresponding *engine locales*:

```
<engine>: {
    # SearXNG string : engine-string
    'ca-ES'          : 'ca_ES',
    'fr-BE'          : 'fr_BE',
    'fr-CA'          : 'fr_CA',
    'fr-CH'          : 'fr_CH',
    'fr'             : 'fr_FR',
    ...
    'pl-PL'          : 'pl_PL',
    'pt-PT'          : 'pt_PT'
    ..
    'zh'             : 'zh'
    'zh_Hans'        : 'zh'
    'zh_Hant'        : 'zh_TW'
}
```

#### Hint

The *SearXNG locale* string has to be known by babel!

If there is no direct 1:1 mapping, this functions tries to narrow down
engine’s language (locale). If no value can be determined by these
approximation attempts the `default` value is returned.

Assumptions:

1. When user select a language the results should be optimized according to
   the selected language.
2. When user select a language and a territory the results should be
   optimized with first priority on territory and second on language.

First approximation rule (*by territory*):

> When the user selects a locale with territory (and a language), the
> territory has priority over the language. If any of the official languages
> in the territory is supported by the engine (`engine_locales`) it will
> be used.

Second approximation rule (*by language*):

> If “First approximation rule” brings no result or the user selects only a
> language without a territory. Check in which territories the language
> has an official status and if one of these territories is supported by the
> engine.

searx.locales.match_locale(searxng_locale: str, locale_tag_list: list[str], fallback: str | None = None) → str | None[source] : Return tag from locale_tag_list that best fits to searxng_locale.

Parameters:
:   - **searxng\_locale** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – SearXNG’s internal representation of locale (de,
      de-DE, fr-BE, zh, zh-CN, zh-TW ..).
    - **locale\_tag\_list** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – The list of locale tags to select from
    - **fallback** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – fallback locale tag (if unset –> `None`)

The rules to find a match are implemented in [`get_engine_locale`](#searx.locales.get_engine_locale),
the `engine_locales` is build up by [`build_engine_locales`](#searx.locales.build_engine_locales).

#### Hint

The *SearXNG locale* string and the members of `locale_tag_list` has to
be known by babel! The [`ADDITIONAL_TRANSLATIONS`](#searx.locales.ADDITIONAL_TRANSLATIONS) are used in the
UI and are not known by babel –> will be ignored.

searx.locales.build_engine_locales(tag_list: list[str]) → dict[str, str][source] : From a list of locale tags a dictionary is build that can be passed by argument engine_locales to get_engine_locale. This function is mainly used by match_locale and is similar to what the fetch_traits(..) function of engines do.

If there are territory codes in the `tag_list` that have a *script code*
additional keys are added to the returned dictionary.

```
>>> import locales
>>> engine_locales = locales.build_engine_locales(['en', 'en-US', 'zh', 'zh-CN', 'zh-TW'])
>>> engine_locales
{
    'en': 'en', 'en-US': 'en-US',
    'zh': 'zh', 'zh-CN': 'zh-CN', 'zh_Hans': 'zh-CN',
    'zh-TW': 'zh-TW', 'zh_Hant': 'zh-TW'
}
>>> get_engine_locale('zh-Hans', engine_locales)
'zh-CN'
```

This function is a good example to understand the language/region model
of SearXNG:

> SearXNG only distinguishes between **search languages** and **search
> regions**, by adding the *script-tags*, languages with *script-tags* can
> be assigned to the **regions** that SearXNG supports.

Copyright © SearXNG team

Made with Furo

💾 🌐