Skip to content

Quick Start

Installation

pip install -U sl10n    

pip install -U "sl10n @ git+https://github.com/SyberiaK/sl10n@main"

Warning

This version may have a lot of bugs. Please don't use it in production code.

Import the library

To start working with sl10n, we need to import the main parts of the library.

1
from sl10n import SL10n, SLocale

Define a locale container

Locale container is an important part of sl10n functionality. Create a SLocale subclass and define all translation keys you will have.

1
2
3
4
5
6
7
8
from sl10n import SLocale


class MyLocale(SLocale):
    greetings_text: str
    main_menu_title: str
    success_text: str
    error_text: str

Note

All locale container strings, even multiline ones, have str type.

Initialize the SL10n

To reference the SL10n system, create an SL10n object.

1
2
3
4
5
6
7
8
9
from sl10n import SL10n, SLocale

class MyLocale(SLocale):
    greetings_text: str
    main_menu_title: str
    success_text: str
    error_text: str

sl10n = SL10n(MyLocale)

Warning

You can't use SLocale directly in SL10n. Treat it as an abstract dataclass.

You can also define a path where your translation files are stored, what language is default, what filenames should be ignored and what parsing implementation (implements pimpl.ParsingImpl) to use:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from pathlib import Path
from sl10n import SL10n, SLocale
from sl10n.pimpl import JSONImpl
import ujson  # not a stdlib


class MyLocale(SLocale):
    greetings_text: str
    main_menu_title: str
    success_text: str
    error_text: str


sl10n = SL10n(MyLocale, Path.cwd() / 'data',
              default_lang='de',
              ignore_filenames=['tags', 'config'],
              parsing_impl=JSONImpl(ujson))

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():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from sl10n import SL10n, SLocale

class MyLocale(SLocale):
    greetings_text: str
    main_menu_title: str
    success_text: str
    error_text: str

sl10n = SL10n(MyLocale)
sl10n.init()

Tip

SL10n.init() returns a reference to your SL10n object, so you can use this oneline to initialize it immediately:

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

Put your strings into translation files

At first init, SL10n will create a default translation file ([working_dir]/lang/en.json by default). It will look like this: 

{
  "greetings_text": "greetings_text",
  "main_menu_title": "main_menu_title",
  "success_text": "success_text",
  "error_text": "error_text"
}

Put in your actual text.

{
  "greetings_text": "Hello World!",
  "main_menu_title": "Main menu",
  "success_text": [
    "Success!",
    "Now you can go back."
  ],
  "error_text": [
    "Error!",
    "Please try again."
  ]
}

Later on, you can use modifiers in these files.

{
  "greetings_text": "Hello World!",
  "main_menu_title": "Main menu",
  "success_text": [
    "Success!",
    "Now you can go back."
  ],
  "error_text": [
    "Error!",
    "Please try again."
  ], 
  "$redump": true  // redumps the file anyway
}

You can also create new lang files: 

1
2
sl10n = SL10n(MyLocale)
sl10n.create_lang_file('de')

Tip

You can pass in override argument to override existing file.

1
sl10n.create_lang_file('fr', override=True)

Warning

You can create lang files only before SL10n init.

1
2
sl10n = SL10n(MyLocale).init()
sl10n.create_lang_file('de')  # file not created, SL10nAlreadyInitialized warning

This is important to ensure that all translation files were initialized.

Get needed locale

After initializing the SL10n, you can access your locale by using SL10n.locale(lang).

1
2
3
4
# Type hint to ensure highlighting unknown attributes
locale: MyLocale = l10n.locale()

print(locale.greetings_text)  # Hello World!

You can access locale strings just like object attributes. If you do need to use a string key:

1
2
3
4
locale = l10n.locale('de')
key = f()  # 'greetings_text'

print(locale.get(key))  # Hallo Welt!

Warning

If you pass an undefined key to locale.get(key) - it will return the key itself.

1
print(locale.get('unknown_key'))  # unknown_key

Set up locale lookups

You can define this function for fast locale lookups:

1
2
3
4
5
6
7
_l10n = SL10n(MyLocale)  # private implementation detail, don't access it directly


def locale(lang: str = None) -> MyLocale:
    if not _l10n.initialized:
        _l10n.init()  # init at first time
    return _l10n.locale(lang)

Basic template

To summarize it up, here's the basic template for sl10n integration you can use as a starting point:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from sl10n import SL10n, SLocale


class MyLocale(SLocale):
    greetings_text: str
    main_menu_title: str
    success_text: str
    error_text: str


_l10n = SL10n(MyLocale)


def locale(lang: str = None) -> MyLocale:
    if not _l10n.initialized:
        _l10n.init()
    return _l10n.locale(lang)


def main():
    loc = locale()  # returns default locale ('en' here)
    print(loc.greetings_text)  # Hello World!


if __name__ == "__main__":
    main()

If you want to know more details about each part of sl10n - check other pages.