foliplus.locale

Localization support for foliplus UI components.

Provides language-specific string tables for all frontend UI text and a helper to inject the correct locale into Jinja2 templates.

Usage

>>> from foliplus import HeatmapControl

# String input (recommended) >>> HeatmapControl(locale=”zh”) >>> HeatmapControl(locale=”en”)

# Load from external JSON >>> from foliplus.locale import LocaleConfig >>> HeatmapControl(locale=LocaleConfig.from_json(“my_locale.json”))

Functions

resolve_locale(locale)

Normalise a locale parameter to a LocaleConfig instance.

Classes

LocaleConfig([language])

Locale configuration for a control instance.

class foliplus.locale.LocaleConfig(language: str = 'en')

Bases: object

Locale configuration for a control instance.

Stores the selected language code and provides string lookup.

Parameters

languagestr, default “en”

Language code, e.g. "en", "zh". Falls back to English if the code is not in _LOCALES_TABLES.

tabledict or None

Optional custom string table (key → localized text). If provided, language is only used to set locale.code.

Examples

>>> LocaleConfig("zh")
>>> LocaleConfig("en")
>>> LocaleConfig(table={"locale.code": "ja", "hello": "こんにちは"})

language: str = 'en'

classmethod from_json(path: str | Path) → LocaleConfig

Load locale strings from an external JSON file.

The file must contain a flat dictionary of key: "translated text" entries, plus a locale.code key that identifies the language.

Parameters

pathstr or Path

Path to a .json file.

Returns

LocaleConfig

Examples

>>> LocaleConfig.from_json("locales/ja.json")

to_json(path: str | Path) → None

Export the current string table to a JSON file.

get(key: str, default: str | None = None) → str

Look up a localized string by key.

property code: str

foliplus.locale.resolve_locale(locale: str | LocaleConfig) → LocaleConfig

Normalise a locale parameter to a LocaleConfig instance.

Parameters

localestr or LocaleConfig

Language code ("en", "zh") or a LocaleConfig instance.

Returns

LocaleConfig

Raises

ValueError

If locale is a string not in _LOCALES_TABLES, or if it is neither a string nor a LocaleConfig.