modern-i18n — это легковесная библиотека для интернационализации Python-проектов. Она позволяет легко управлять переводами, использовать параметризованные строки для форматирования текста. Подходит для небольших и крупных проектов.

Для кого это статья?

Статья предназначена для разработчиков проектов на Python, которые хотят внедрить в свой проект интернационализацию (поддержку нескольких языков).

Введение

В современных приложениях, особенно тех, что используются в международной среде, поддержка нескольких языков (интернационализация — i18n) является критически важным аспектом. Modern-i18n — это библиотека для Python, которая упрощает и делает процесс локализации более эффективным и понятным. Она предлагает удобный API, поддерживает JSON-формат для хранения переводов и обеспечивает гибкость настройки.

Почему я разработал собственный i18n?

Основные причины:

• Упрощение работы с переводами

  Многие популярные библиотеки i18n требуют сложной настройки и обладают избыточным API. Я хотел создать решение, которое будет простым, понятным и удобным для использования.

• Минимизация зависимостей

  Некоторые библиотеки i18n требуют установки дополнительных пакетов, что может усложнять развертывание. Modern-i18n работает без них.

• Легкость и производительность

  Библиотека modern-i18n не зависит от сторонних библиотек и легко интегрируется в любой проект. Она загружает только необходимые данные и использует механизм кэширования для повышения скорости работы.

• Гибкость

  Библиотека может использоваться как в чистых проектах на Python, так и с web-фреймворками (Flask, Django и др.).

• Самостоятельность и контроль

  Создавая собственную реализацию, я получил возможность полностью контролировать её поведение, улучшать её по мере необходимости и адаптировать под конкретные задачи проекта.

Установка

Для установки библиотеки воспользуйтесь пакетным менеджером pip:

pip install modern-i18n

Структура проекта

Для внедрения i18n необходимо создать в свой проект новые папки и файлы. Пример типовой структуры проекта после настройки библиотеки modern-i18n:

project/
├── i18n/              # ? Модуль интернационализации
│   └── config.py      # ? Конфигурационный файл: язык по умолчанию, путь к переводам и т.д.
│
├── locale/            # ? Директория с переводами (локализациями)
│   ├── en/            # ? Английская локаль
│   │   └── translation.json  # ? Файл с переводами на английский язык
│   └── ru/            # ? Русская локаль
│       └── translation.json  # ? Файл с переводами на русский язык
│
└── example.py         # ? Пример использования функции перевода

Конфигурация

Все настройки библиотеки находятся в файле i18n/config.py. Пример базовой конфигурации:

import os
from pathlib import Path

from modern_i18n.i18n import I18n

project_root = Path(__file__).resolve().parent.parent
LOCALE_PATH = os.path.join(project_root, 'locale')

config = {
    'locale_path': LOCALE_PATH,  # Путь к директории с переводами
    'locales': ['ru', 'en'],  # Список доступных языков
    'default_locale': 'ru',  # Язык по умолчанию
    'default_encoding': 'UTF-8'  # Кодировка для файлов перевода по умолчанию 'UTF-8'
}

i18n = I18n(config)
t = i18n.translate

• В файле i18n/config.py настраиваются основные параметры: список доступных языков, язык по умолчанию, путь к директории с переводами и дополнительные опции.

• Все переводы хранятся в формате JSON внутри директории locale, где каждая локаль имеет свою собственную папку.

Формат переводов

Переводы хранятся в файлах translation.json, где каждый ключ — это оригинальная фраза, а значение — её перевод на нужный язык.

Пример для английского языка (locale/en/translation.json):

{
  "Итого {a}+{b}={total}": "Total {a}+{b}={total}.",
  "Количество языков на планете бесчисленное множество": "There are countless languages on the planet",
  "Ограничение длины строки: {str:.6}": "String length limit: {str:.6}",
  "Процент: {percent:.0%}": "Percentage: {percent:.0%}",
  "Процент: {percent:.1%}": "Percentage: {percent:.1%}",
  "Процент: {percent:.2%}": "Percentage: {percent:.2%}",
  "Сегодня: {date:%A, %B %d, %Y}": "Today: {date:%A, %B %d, %Y}",
  "Сегодня: {date:%d.%m.%Y}": "Today: {date:%d.%m.%Y}",
  "Сегодня: {date}": "Today: {date}",
  "Число с плавающей точкой: {number:.0f}": "Floating point number: {number:.0f}",
  "Число с плавающей точкой: {number:.3f}": "Floating point number: {number:.3f}"
}

Пример для русского языка (locale/ru/translation.json):

{
  "Итого {a}+{b}={total}": "Итого {a}+{b}={total}.",
  "Количество языков на планете бесчисленное множество": "Количество языков на планете бесчисленное множество",
  "Ограничение длины строки: {str:.6}": "Ограничение длины строки: {str:.6}",
  "Процент: {percent:.0%}": "Процент: {percent:.0%}",
  "Процент: {percent:.1%}": "Процент: {percent:.1%}",
  "Процент: {percent:.2%}": "Процент: {percent:.2%}",
  "Сегодня: {date:%A, %B %d, %Y}": "Сегодня: {date:%A, %B %d, %Y}",
  "Сегодня: {date:%d.%m.%Y}": "Сегодня: {date:%d.%m.%Y}",
  "Сегодня: {date}": "Сегодня: {date}",
  "Число с плавающей точкой: {number:.0f}": "Число с плавающей точкой: {number:.0f}",
  "Число с плавающей точкой: {number:.3f}": "Число с плавающей точкой: {number:.3f}"
}

⚠️ Важно: все ключи должны быть одинаковыми во всех файлах, чтобы обеспечить корректное сопоставление.

ℹ️ По моему опыту по внедрению i18n в большие проекты, в качестве ключей рекомендую использовать те названия, которые уже есть у Вас на проекте.

Например, у Вас есть строковые переменные, которые нужно интернационализировать.

До внедрения i18n:

s = 'Количество языков на планете бесчисленное множество'

Вы просто берете эту строку и оборачиваете ее в функцию t.

После внедрения i18n:

from i18n.config import t

s = t('Количество языков на планете бесчисленное множество', locale='en')

В результате получаете ту же читаемость кода, что и была. Плюс избавляет Вас от придумывания ключей, что сэкономит Вам много времени, особенно когда проект большой.

Использование библиотеки

После конфигурации вы можете использовать функцию t для получения перевода.

from i18n.config import t

print(t('Количество языков на планете бесчисленное множество'))  # -> Количество языков на планете бесчисленное множество
# Перевод с указанием локали
print(t('Количество языков на планете бесчисленное множество', locale='en'))  # -> There are countless languages on the planet

Перевод с параметрами

print(t('Итого {a}+{b}={total}', a=5, b=10, total=15))  # -> Итого 5+10=15.
print(t('Итого {a}+{b}={total}', locale='en', a=5, b=10, total=15))  # -> Total 5+10=15.

Форматируемый перевод

Библиотека позволяет гибко форматировать строки, используя именованные аргументы, а также спецификаторы формата для чисел, строк и дат.

import datetime

# Число с плавающей точкой
print(t("Число с плавающей точкой: {number:.3f}", locale='en', number=3.14159))  # -> Floating point number: 3.142
print(t("Число с плавающей точкой: {number:.0f}", locale='en', number=3.5))  # -> Floating point number: 4

# Проценты
print(t("Процент: {percent:.2%}", locale='en', percent=0.736))  # -> Percentage: 73.60%
print(t("Процент: {percent:.1%}", locale='en', percent=0.736))  # -> Percentage: 73.6%
print(t("Процент: {percent:.0%}", locale='en', percent=0.736))  # -> Percentage: 74%

# Форматирование даты
today = datetime.date.today()
print(t("Сегодня: {date}", date=today))  # -> Сегодня: 2025-07-10
print(t("Сегодня: {date:%d.%m.%Y}", date=today))  # -> Сегодня: 10.07.2025
print(t("Сегодня: {date:%A, %B %d, %Y}", locale='en', date=today))  # -> Today: Thursday, July 10, 2025

# Ограничение длины строки
print(t("Ограничение длины строки: {str:.6}", locale='en', str="Привет мир!"))  # -> String length limit: Привет

Обработка отсутствующих ключей

Если ключ не найден, библиотека выдаст предупреждение и вернёт исходную строку:

print(t('Ключ не существует'))  # Warning -> Ключ не существует

Заключение

Modern-i18n — это мощная и простая в использовании библиотека для интернационализации Python-проектов. Она позволяет быстро настраивать локализацию, поддерживает работу с несколькими языками и параметризованными строками. Благодаря своей гибкости и лёгкости, она станет отличным выбором для разработчиков, которым нужно создать многоязычное приложение без лишней сложности.

Эта библиотека используется в реальных проектах и продолжает развиваться. Если вы сталкиваетесь с задачей локализации в Python-приложениях, обязательно попробуйте modern-i18n — возможно, она станет вашим идеальным выбором.

Ссылка на библиотеку

Буду рад обратной связи. В комментариях напишите, а как Вы решаете данную задачу.