locale module

class fluent_anvil.locale.Locale

Bases: list

Models a locale and its fallbacks.

The Locale class is a list. As such it can contain one primary locale at index 0 and multiple fallback locales at the following indices.

__init__(locale: str = None)
classmethod auto(fallback: str = None, count: int = 10)

Automatically select the most preferable locales for the user.

Selects the most preferable locales for the user that are currently available.

Parameters:

  • index_url – The URL to the index.lst file containing a list of all available locales (one locale per line). If not given, the default index.lst file will be used.

  • fallback – The locale to use if the operation fails. If not given, the default fallback locale will be used.

  • count – The maximum number of fallback locales to use.

classmethod clean(locale)

Ensure valid IETF language tags.

Since Anvil does not support hyphens for directories, users may use an underscore for the locale names as well. However, this would not be valid IETF language tags. Therefore, replace any underscores with hyphens. The JavaScript library will switch to underscore again when loading the assets.

Parameters:

locale – String or iterable of locale strings, e.g., “en-US”.

classmethod compose(pattern: dict, components: dict)

Create a locale given a pattern and its components.

decompose(index: int = 0) → dict

Decompose the locale or one of its fallbacks into its components.

Decompose the locale (index = 0) or one of its fallbacks (index > 0) into its components. Returns a dictionary which contains the locale’s components as keys and the corresponding values as dictionary values.

classmethod match(requested: list, available: list = None, fallback: str = None, count: int = 10, force_py=False)

For the given requested locales, return the best matching available locales.

Given a list of requested locales and locales available (i.e. those supported by the application), the method returns an ordered list of available locales that best fit any of the requested locales. The first locale in the returned list is the one with the best fit. If there is no sensible match, the fallback is returned (e.g., the application’s primary / best supported language or a widely spoken locale like English).

Parameters:

  • requested – A single locale or a list of locales that the user prefers.

  • available – A list of locales that the application supports. If not given, the default index.lst file will be used.

  • fallback – The locale to return if no sensible match is found. If not given, the default fallback locale will be used.

  • count – The maximum number of fallback locales to use.

  • force_py – Force the use of the Python implementation of the matching algorithm instead of the JavaScript one.

classmethod preferred(fallback: str = None) → list

Return the user’s preferred locales.

Uses the Get-User-Locale library https://github.com/wojtekmaj/get-user-locale .

Parameters:

fallback – The fallback locale to return if operation fails. If not given, the default fallback locale will be used.

classmethod select(available: list)

Select the user’s most preferred locale given the available locales.

Parameters:

available – List of locales available.

fallback = 'en'

The default fallback locale to use if no other locale is found.

The value will be modified automatically whenever fluent instance is reconfigured.

index_url = './_/theme/localization/index.lst'

The default URL to the index.lst file that contains all available locales.

The value will be modified automatically whenever fluent instance is reconfigured.

max_distance = 100

Maximum matching distance between requested locale and available locales.

property requested

Return the locales that were originally requested.

This is useful if the localization .ftl files are switched and the originally requested locales shall be matched against the new .ftl files again.