Registry / serialization / i18nice

i18nice

JSON →
library0.16.0pypypi✓ verified 92d ago

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.

pip install i18nice
INSTALL
IMPORT
SIG · I18NICE
I
i18nice
serializationpythonv0.16.0
Install
1.6s avg
Import
101ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.101s · 20.1MB
glibc
py 3.10–3.940 runs
installs and imports cleanly · install 1.6s · import 0.100s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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')
Debug
Known issues
breakingPython 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.
affects: >=0.16.0
breakingThe `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', ...)`.
affects: >=0.16.0
breakingCustom 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]`.
affects: 0.14.0, 0.15.0
gotchaThe 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'])`.
affects: All versions with YAML support after change (exact version not specified, but mentioned in docs)
gotchaPluralization 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.
affects: >=0.15.2
Errors
Common errors & fixes
TypeError: 'key' is a positional-only argument and cannot be passed as keyword argument
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.
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.
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.
Upgrade
Version history
0.16.0latest on PyPI · released May 29, 2025
Audit
Dependencies
PyYAMLoptionalRequired for loading translations from YAML files. Install with `pip install i18nice[YAML]` or `pip install PyYAML`.
Agent activity
4 hits · last 30 days
node
4
Resources
i18nice — pip install i18nice · libregistry