pydantic-i18n 0.1.0

Top-level package for pydantic-i18n.

pydantic-i18n is an extension to support an i18n for the pydantic error messages.

---

Documentation: https://pydantic-i18n.boardpack.org

Source Code: https://github.com/boardpack/pydantic-i18n

---

Requirements

Python 3.6+

pydantic-i18n has the next dependencies:

• Pydantic
• Babel

Installation

$ pip install pydantic-i18n

---> 100%

First steps

To start to work with pydantic-i18n, you can just create a dictionary (or create any needed translations storage and then convert it into dictionary) and pass to the main PydanticI18n class.

To translate messages, you need to pass result of exception.errors() call to the translate method:

from pydantic import BaseModel, ValidationError
from pydantic_i18n import PydanticI18n


translations = {
    "en_US": {
        "field required": "field required",
    },
    "de_DE": {
        "field required": "Feld erforderlich",
    },
}

tr = PydanticI18n(translations)


class User(BaseModel):
    name: str


try:
    User()
except ValidationError as e:
    translated_errors = tr.translate(e.errors(), locale="de_DE")

print(translated_errors)
# [
#     {
#         'loc': ('name',),
#         'msg': 'Feld erforderlich',
#         'type': 'value_error.missing'
#     }
# ]

(This script is complete, it should run "as is")

In the next chapters, you will see current available loaders and how to implement your own loader.

Get current error strings from Pydantic

pydantic-i18n doesn't provide prepared translations of all current error messages from pydantic, but you can use a special class method PydanticI18n.get_pydantic_messages to load original messages in English. By default, it returns a dict object:

from pydantic_i18n import PydanticI18n

print(PydanticI18n.get_pydantic_messages())
# {
#     "field required": "field required",
#     "extra fields not permitted": "extra fields not permitted",
#     "none is not an allowed value": "none is not an allowed value",
#     "value is not none": "value is not none",
#     "value could not be parsed to a boolean": "value could not be parsed to a boolean",
#     "byte type expected": "byte type expected",
#     .....
# }

(This script is complete, it should run "as is")

You can also choose JSON string or Babel format with output parameter values "json" and "babel":

from pydantic_i18n import PydanticI18n

print(PydanticI18n.get_pydantic_messages(output="json"))
# {
#     "field required": "field required",
#     "extra fields not permitted": "extra fields not permitted",
#     "none is not an allowed value": "none is not an allowed value",
#     .....
# }

print(PydanticI18n.get_pydantic_messages(output="babel"))
# msgid "field required"
# msgstr "field required"
#
# msgid "extra fields not permitted"
# msgstr "extra fields not permitted"
#
# msgid "none is not an allowed value"
# msgstr "none is not an allowed value"
# ....

(This script is complete, it should run "as is")

Loaders

pydantic-i18n provides a list of loaders to use translations.

DictLoader

DictLoader is the simplest loader and default in PydanticI18n. So you can just pass your translations dictionary without any other preparation steps.

from pydantic import BaseModel, ValidationError
from pydantic_i18n import PydanticI18n


translations = {
    "en_US": {
        "field required": "field required",
    },
    "de_DE": {
        "field required": "Feld erforderlich",
    },
}

tr = PydanticI18n(translations)


class User(BaseModel):
    name: str


try:
    User()
except ValidationError as e:
    translated_errors = tr.translate(e.errors(), locale="de_DE")

print(translated_errors)
# [
#     {
#         'loc': ('name',),
#         'msg': 'Feld erforderlich',
#         'type': 'value_error.missing'
#     }
# ]

(This script is complete, it should run "as is")

JsonLoader

JsonLoader needs to get the path to some directory with the next structure:

|-- translations
    |-- en_US.json
    |-- de_DE.json
    |-- ...

where e.g. en_US.json looks like:

{
    "field required": "field required"
}

and de_DE.json:

{
    "field required": "Feld erforderlich"
}

Then we can use JsonLoader to load our translations:

from pydantic import BaseModel, ValidationError
from pydantic_i18n import PydanticI18n, JsonLoader

loader = JsonLoader("./translations")
tr = PydanticI18n(loader)


class User(BaseModel):
    name: str


try:
    User()
except ValidationError as e:
    translated_errors = tr.translate(e.errors(), locale="de_DE")

print(translated_errors)
# [
#     {
#         'loc': ('name',),
#         'msg': 'Feld erforderlich',
#         'type': 'value_error.missing'
#     }
# ]

(This script is complete, it should run "as is")

BabelLoader

BabelLoader works in the similar way as JsonLoader. It also needs a translations directory with the next structure:

|-- translations
    |-- en_US
        |-- LC_MESSAGES
            |-- messages.mo
            |-- messages.po
    |-- de_DE
        |-- LC_MESSAGES
            |-- messages.mo
            |-- messages.po
    |-- ...

Information about translations preparation you can find on the Babel docs pages{:target="_blank"} and e.g. from this article{:target="_blank"}.

Here is an example of the BabelLoader usage:

from pydantic import BaseModel, ValidationError
from pydantic_i18n import PydanticI18n, BabelLoader

loader = BabelLoader("./translations")
tr = PydanticI18n(loader)


class User(BaseModel):
    name: str


try:
    User()
except ValidationError as e:
    translated_errors = tr.translate(e.errors(), locale="de")

print(translated_errors)
# [
#     {
#         'loc': ('name',),
#         'msg': 'Feld erforderlich',
#         'type': 'value_error.missing'
#     }
# ]

(This script is complete, it should run "as is")

Write your own loader

If current loaders aren't suitable for you, it's possible to write your own loader and use it with pydantic-i18n. To do it, you need to import BaseLoader and implement the next items:

• property locales to get a list of locales;
• method get_translations to get content for the specific locale.

In some cases you will also need to change implementation of the gettext method.

Here is an example of the loader to get translations from CSV files:

|-- translations
    |-- en_US.csv
    |-- de_DE.csv
    |-- ...

en_US.csv content:

field required,field required

de_DE.csv content:

field required,Feld erforderlich

import os
from typing import List, Dict

from pydantic import BaseModel, ValidationError
from pydantic_i18n import PydanticI18n, BaseLoader


class CsvLoader(BaseLoader):
    def __init__(self, directory: str):
        self.directory = directory

    @property
    def locales(self) -> List[str]:
        return [
            filename[:-4]
            for filename in os.listdir(self.directory)
            if filename.endswith(".csv")
        ]

    def get_translations(self, locale: str) -> Dict[str, str]:
        with open(os.path.join(self.directory, f"{locale}.csv")) as fp:
            data = dict(line.strip().split(",") for line in fp)

        return data


class User(BaseModel):
    name: str


if __name__ == '__main__':
    loader = CsvLoader("./translations")
    tr = PydanticI18n(loader)

    try:
        User()
    except ValidationError as e:
        translated_errors = tr.translate(e.errors(), locale="de")

    print(translated_errors)
    # [
    #     {
    #         'loc': ('name',),
    #         'msg': 'Feld erforderlich',
    #         'type': 'value_error.missing'
    #     }
    # ]

(This script is complete, it should run "as is")

Acknowledgments

Thanks to Samuel Colvin and his pydantic library.

Also, thanks to Sebastián Ramírez and his FastAPI project, some scripts and documentation structure and parts were used from there.

License

This project is licensed under the terms of the MIT license.