i18nice

0.16.0 · active · verified Thu Apr 16

i18nice is a Python library that provides internationalization (i18n) functionality, largely inspired by the Rails i18n library. It simplifies translation management for Python 3 applications by supporting translation files (JSON, YAML), placeholders, pluralization, and fallback locales. The current version is 0.16.0, and it maintains a relatively active release cadence with minor and patch updates.

Common errors

```
TypeError: 'key' is a positional-only argument and cannot be passed as keyword argument
```
cause Attempting to call `i18n.t(key='your.key')` or similar, where 'key' is passed as a keyword argument.

fix Pass the translation key as the first positional argument: `i18n.t('your.key', ...)`.
```
i18n.t('some.key') returns 'some.key' (the key itself) instead of translated text.
```
cause The translation for 'some.key' was not found for the current locale or the translation files were not loaded correctly. This can happen if `i18n.load_path` is incorrect or the key does not exist in the files.

fix Verify that `i18n.load_path` points to the correct directory containing your translation files, ensure your locale is set (`i18n.set('locale', 'en')`), and confirm the key exists within your translation files and matches the file namespace (e.g., `app.greeting` for `app.en.json`). Use `i18n.load_everything()` to explicitly load all translations.
```
Error loading YAML translation file, potentially related to missing features.
```
cause The default YAML loader in `i18nice` no longer uses `yaml.FullLoader`, which might lead to issues if your YAML files use advanced features (e.g., custom tags, anchors).

fix If your YAML files are complex, you may need to register a custom YAML loader that explicitly uses `yaml.FullLoader` to restore full YAML parsing capabilities. Refer to the i18nice documentation for the exact implementation.

Warnings

breaking Python 3.6 and 3.7 support has been officially dropped in version 0.16.0.
Fix: Upgrade to Python 3.8 or newer to use i18nice v0.16.0 and later.
breaking The `key` argument in `i18n.t()` is now positional-only as of version 0.16.0.
Fix: Ensure the key for translation is always passed as the first positional argument, e.g., `i18n.t('your.key', ...)` instead of `i18n.t(key='your.key', ...)`.
breaking Custom function interfaces underwent significant changes in versions 0.14.0 and 0.15.0. If you used custom translation functions, their signatures will need updating.
Fix: For v0.14.0, change `lambda **kw: kw['count'] != 1` to `lambda a, **kw: a[kw['count'] != 1]`. For v0.15.0, change to `lambda *a, **kw: a[kw['count'] != 1]`.
gotcha The default YAML loader no longer uses `yaml.FullLoader`. If your YAML translation files rely on full YAML functionalities (e.g., tags, anchors), they might not load correctly.
Fix: Register a custom YAML loader that uses `yaml.FullLoader` if needed. Example: `class MyLoader(i18n.loaders.YamlLoader): loader = yaml.FullLoader; i18n.register_loader(MyLoader, ['yml', 'yaml'])`.
gotcha Pluralization logic was refined in v0.15.2; a dictionary is now considered plural only if all its keys (`one`, `many`, `zero`, `few`) are explicitly plural forms.
Fix: Review pluralization dictionary structures to ensure all keys conform to expected plural forms, or adjust your translation data if you relied on previous implicit pluralization.

Install

pip install i18nice Base installation
pip install i18nice[YAML] Installation with YAML support

Imports

i18n
```
import i18n
```
The library's core functionality is exposed through the `i18n` module itself.

Quickstart

This quickstart demonstrates how to set up `i18nice` by adding a translation path, setting the locale, and performing basic string translation with placeholders and pluralization using a simple JSON file.

import i18n
import os

# Create a dummy translation directory and file
# In a real application, these would be pre-existing
if not os.path.exists('translations'):
    os.makedirs('translations')
with open('translations/app.en.json', 'w') as f:
    f.write('{
  "greeting": "Hello %{name}!",
  "mails": {
    "zero": "You have no mails.",
    "one": "You have one mail.",
    "other": "You have %{count} mails."
  }
}')

# Configure i18n to load translations from the 'translations' directory
i18n.load_path.append('translations')
i18n.set('locale', 'en')

# Translate a simple string with a placeholder
message = i18n.t('app.greeting', name='World')
print(message) # Expected: Hello World!

# Translate with pluralization
message_zero = i18n.t('app.mails', count=0)
message_one = i18n.t('app.mails', count=1)
message_many = i18n.t('app.mails', count=5)

print(message_zero) # Expected: You have no mails.
print(message_one)  # Expected: You have one mail.
print(message_many) # Expected: You have 5 mails.

# Clean up dummy file and directory
os.remove('translations/app.en.json')
os.rmdir('translations')

view raw JSON →