API Reference

SL10n

SL10n(
    locale_container: Type[T],
    path: Path | PathLike = default_path,
    *,
    default_lang: str = "en",
    ignore_filenames: Iterable[str] = (),
    parsing_impl: ParsingImpl = default_pimpl,
    strict: bool = False,
    warn_unfilled_keys: bool = False
)

Bases: Generic[T]

Static text localization system.

To use it, first create a locale container (it MUST be a subclass of SLocale) and define some string keys in it:

class MyLocale(sl10n.SLocale):
    my_key_1: str
    my_key_2: str
    ...

After that, create an SL10n object and pass in your locale container:

l10n = sl10n.Sl10n(MyLocale)

Note that it only creates a reference to your localization system. To load all locale files and pack their content into locale containers, call SL10n.init() method:

l10n = sl10n.Sl10n(MyLocale)
...
l10n.init()

Parameters:

Name	Type	Description	Default
locale_container	Type[T]	Locale container to use. It must be a SLocale subclass.	required
path	str | PathLike | Path	Path to your translation files directory. Defaults to pathlib.Path.cwd() / 'lang'.	default_path
default_lang	str	Default language. Defaults to 'en'.	'en'
ignore_filenames	Iterable[str]	What filenames the parser should ignore. Defaults to ().	()
parsing_impl	ParsingImpl	What parsing implementation to use. Defaults to pimpl.JSONImpl(json, indent=2, ensure_ascii=False).	default_pimpl

Raises:

Type	Description
TypeError	When locale_container is not an SLocale subclass or is an SLocale itself.

create_lang_file

create_lang_file(lang: str, override: bool = False)

Creates a sample lang file in a requested path. If you want to override existing file - set override to True.

Useful for fast lang file creation.

Example

l10n = sl10n.Sl10n(MyLocale).init()
l10n.create_lang_file('de')

Parameters:

Name	Type	Description	Default
lang	str	Language of translations in this file (used as filename).	required
override	bool	If True, existing file will be overwritten. Defaults to False.	False

Warns:

Type	Description
SL10nAlreadyInitialized	If SL10n is initialized.
LangFileAlreadyExists	When the file already exists and override set to False

Warning

Can be called only before SL10n initialization.

init

init() -> Self

Load all locale files and pack their content into locale containers.

You must call it to access your localization.

Example

l10n = sl10n.Sl10n(MyLocale)
...
l10n.init()

It also returns a reference to your SL10n object, so you can use this oneline to init immediately:

l10n = sl10n.Sl10n(MyLocale).init()

Warns:

Type	Description
SL10nAlreadyInitialized	When Sl10n is already initialized.

locale

locale(lang: str | None = None) -> T

Returns a locale container, containing all defined string keys translated to the requested language (if such translation exists, otherwise returns a default one).

Example

l10n = sl10n.Sl10n(MyLocale).init()

locale: MyLocale = l10n.locale('en')
print(locale.my_key_1)

Parameters:

Name	Type	Description	Default
lang	str	Language you want to get.	None

Raises:

Type	Description
SL10nIsNotInitialized	When SL10n isn't initialized.

Tip

We do recommend to type hint a variable where you would store a locale container. Some IDEs (like PyCharm) may fail to highlight unresolved attributes if you don't do so.

locale: MyLocale = l10n.locale('en')

print_modifiers_available staticmethod

print_modifiers_available()

Print all modifiers available.

SLocale dataclass

SLocale(lang_code: str | None)

This class contains some specific fields and methods to your locale containers.

Also, you must subclass your locale container from this class to use it in SL10n.

lang_code instance-attribute

lang_code: str | None

Current locale lang code (filename). Can be overwritten only by "$lang_code" modifier.

Sets to None if the container is a sample one.

get

get(key: str) -> str

Returns a string associated with the given key (if such a key exists, otherwise returns the key itself).

Can be used if the key is known only at runtime.

Parameters:

Name	Type	Description	Default
key	str	Key used to get string.	required

Returns:

Type	Description
str	If such a key exists, string associated with the given key.
str	Otherwise, the key itself.

Warns:

Type	Description
UnexpectedLocaleKey	When got an unexpected key.

Example

class MyLocale(sl10n.SLocale):
    my_key_1: str
    my_key_2: str
    ...

...

locale = l10n.locale('en')
my_text_1 = locale.get('my_key_1')  # 'Text 1'

sample classmethod

sample() -> T

Returns:

Type	Description
T	A sample locale container with key names as values.

SLocale.lang_code sets to None.

Example

class MyLocale(sl10n.SLocale):
    my_key_1: str
    my_key_2: str
    ...

sample = MyLocale.sample()  # MyLocale(lang_code=None, my_key_1='my_key_1', my_key_2='my_key_2', ...)

to_dict

to_dict() -> dict[str, str | None]

Returns:

Type	Description
dict[str, str | None]	A dict converted from a locale container.

Example

class MyLocale(sl10n.SLocale):
    my_key_1: str
    my_key_2: str
    ...

...

locale = l10n.locale('en')
locale_dict = locale.to_dict()  # {'lang_code': 'en', my_key_1: 'Text 1', my_key_2: 'Text 2', ...}

warnings

DefaultLangFileNotFound

Bases: UserWarning

Propogates when the default language file not found.

LangFileAlreadyExists

Bases: UserWarning

Propogates when the language file already exists.

SL10nAlreadyInitialized

SL10nAlreadyInitialized(message: str | None = None)

Bases: UserWarning

Propogates when SL10n already initialized.

UndefinedLocale

Bases: UserWarning

Propogates when got an undefined locale.

UndefinedLocaleKey

Bases: UserWarning

Propogates when found an undefined locale key.

UnexpectedLocaleKey

Bases: UserWarning

Propogates when found an unexpected locale key.

UnfilledLocaleKey

Bases: UserWarning

Propogates when found an unfilled (value == key or value is empty) locale key.

UnknownModifier

Bases: UserWarning

Propogates when found an unknown modifier.

pimpl

ParsingImpl

Bases: ABC

Interface for file parsing implementations.

You can inherit from it and define your own parsing implementation for SL10n.

file_ext abstractmethod property

file_ext: str

Returns a string that represents what file extension the parsing implementation works with.

Example

class JSONImpl(ParsingImpl):
    file_ext = 'json'

load abstractmethod

load(file: IO) -> dict[str, Any]

Loads and returns data from a passed IO object (mostly file).

Example

import json

class JSONImpl(ParsingImpl):
    def load(self, file: IO) -> Any:
        return json.load(file)

dump abstractmethod

dump(data: dict[str, Any], file: IO) -> None

Saves data into a passed IO object (mostly file).

Example

import json

class JSONImpl(ParsingImpl):
    def dump(self, data: Any, file: IO) -> None:
        json.dump(data, file)

JSONImpl

JSONImpl(
    module: ModuleType = json, *args: Any, **kwargs: Any
)

Bases: ParsingImpl

Interface for basic JSON parsers implementations (which follow Python's built-in json module interface).

Modules confirmed as supported: json, simplejson, ujson, rapidjson

file_ext class-attribute instance-attribute

file_ext = 'json'

Accepts ".json" files.

ORJSONImpl

ORJSONImpl(*args, **kwargs)

Bases: JSONImpl

Deprecated since 0.3.0.0. Use sl10n.pimpl.JSONImpl() with one of the supported modules instead (e.g., Python's built-in json).

Interface for orjson module.

Please ensure that you have this module installed.