Welcome to Pylocwolowitz’s documentation!


Documentation of the api

class pylocwolowitz.core.Pylocwolowitz(path, format_deserializer='json')[source]

Pylocwolitz is a very simple text localization system.

Pylocwolitz is a very simple text localization system, meant to be used by web applications (but can pretty much be used anywhere). Yes, another localization system.

  • path (str) – File path translation
  • format_deserializer (str) – Indicate the serializer to use json or yaml

ValueError – Format not supported, only json or yaml.

loc(key, lang, values=None)[source]

Get the translate.

Return the string key, translated to the requested language (if such a translation exists, otherwise no traslation occurs). Any other parameters passed to the method are injected to the placeholders in the string (if present).

  • key (str) – Key translate
  • lang (str) – Language to translate
  • values (dict) – Arguments are injected to the placeholders in the string

Translated to the requested language

Return type:


Example of i18n file

Store files in the language folder first argument specified when creating the object.

Use YAML format

Here is an example with one language per file:

"welcome {name}": "Välkommen {name}"
"Hello": "Hej"

An example with two language in the same file:

"welcome {name}":
  "fr": "Bienvenue {name}"
  "en": "Welcome {name}"

Use JSON format

Here is an example with one language per file:

    "welcome {name}": "Välkommen {name}"
    "Hello": "Hej"

An example with two language in the same file:

    "welcome {name}": {
        "fr": "Bienvenue {name}",
        "en": "Welcome {name}"

How to contrib

Choice to use a fairly close process to what is in us in other Free and Open Source Software projects.

It is recommended for a new developer or contributor to read this document.

Create a ticket

For all new features or bug fixes, fill a new ticket in the issue tracker.

Try to be specific in the ticket, with a proper title and description, if you can provide steps to help the developper to understand the process or the feature request. Without enough context, it can be difficult to understand.

The ticket number is then used as a reference for the branch and commits.

Create a branch

Except in exceptional cases, a developer must not directly commits in master.

The rule also applies to project core developers.

The branch must be prefixed by the ticket number, for example:

git pull origin master
git branch 425-assign_nobody

Don’t forget to be update master before creating your new branch from it.

Unit test

Except in exceptional cases, a pull request must come with tests.

It is important to write tests, it’s annoying but it pays in the long run, not regression, refactoring opportunities, and so on.

If this is a bug fix, write a test for this case.

A branch will not merged if there is no test. Learn from the many existing tests, ask questions if needed.

Code review

To err is human, several pair of eyes are better than one.

A developer should not merge in the master.

The code must be reviewed by another developer and merged by an experienced core developer.

It is possible to discuss and point out any mistakes or errors.

If we detect a mistake after the branch as been merged, we will all work together to fix it as soon as possible.

Hook to exec flake8

We want our beautiful code to be PEP8 compliant so it is strongly recommended to add this pre-commit hook in git (peopleask/.git/hooks/pre-commit):

#!/usr/bin/env bash
flake8 ./peopleask/

If not pep8 it will not be commiting


It is important to follow up the process. It is not to be annoying, but it opens the discussion, helps to progress and to have a better quality of code as well as letting every developer sees and valid project progress.

Do not take the critic for you, each developer make mistakes and it is fine.

Despite this process of functional bugs and errors happen and it is fine as well, never forget it.

Indices and tables


Pylocwolowitz is a port of the awesome Locale::Wolowitz module from Perl in Python. It is a very simple text localization system, meant to be used by web applications (but can pretty much be used anywhere).

Yes, this is yet another localization system.

Pylocwolowitz works with JSON and YAML files.

Each file can serve one or more languages. When creating an instance of this module, you are required to pass a path to a directory where your application’s JSON localization files are present. These are all loaded and merged into one big dict, which is stored in memory. A file with only one language has to be named <lang>.json (where <lang> is the name of the language, you’d probably want to use the two-letter ISO 639-1 code). A file with multiple language can be call fr_and_es.json. The basic idea is to write your application in a base language, and use the JSON files to translate text to other languages. For example, lets say you’re writing your application in English and translating it to Hebrew, Spanish, and Dutch. You put Spanish and Dutch translations in one file, and since everybody hates Israel, you put Hebrew translations alone.


from pylocwolowitz import Pylocwolowitz
i18n = Pylocwolowitz('./i18n')
i18n.loc('hello', 'fr')
i18n.loc('welcome {name}', 'se', {'name': 'hobbestigrou'})


Thanks to Ido Perlmuter to Locale::Wolowitz. Thanks you to Julien Tayon for his contributions. A big thank you to Victor Stinner, Marmotte and Ggreg for their invaluable advice.