Metadata-Version: 2.1 Name: python-i18n Version: 0.3.9 Summary: Translation library for Python Home-page: https://github.com/tuvistavie/python-i18n Author: Daniel Perez Author-email: tuvistavie@gmail.com License: MIT Download-URL: https://github.com/tuvistavie/python-i18n/archive/master.zip Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Environment :: Other Environment Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 3 Classifier: Topic :: Software Development :: Libraries Description-Content-Type: text/markdown Provides-Extra: yaml Requires-Dist: pyyaml (>=3.10) ; extra == 'yaml' # python-i18n [![Build Status](https://travis-ci.org/danhper/python-i18n.png?branch=master)](https://travis-ci.org/danhper/python-i18n) [![Coverage Status](https://coveralls.io/repos/github/danhper/python-i18n/badge.svg?branch=master)](https://coveralls.io/github/danhper/python-i18n?branch=master) [![Code Climate](https://codeclimate.com/github/danhper/python-i18n/badges/gpa.svg)](https://codeclimate.com/github/danhper/python-i18n) This library provides i18n functionality for Python 3 out of the box. The usage is mostly based on Rails i18n library. ## Installation Just run pip install python-i18n If you want to use YAML to store your translations, use pip install python-i18n[YAML] ## Usage ### Basic usage The simplest, though not very useful usage would be import i18n i18n.add_translation('foo', 'bar') i18n.t('foo') # bar ### Using translation files YAML and JSON formats are supported to store translations. With the default configuration, if you have the following `foo.en.yml` file en: hi: Hello world ! in `/path/to/translations` folder, you simply need to add the folder to the translations path. import i18n i18n.load_path.append('/path/to/translations') i18n.t('foo.hi') # Hello world ! Please note that YAML format is used as default file format if you have `yaml` module installed. If both `yaml` and `json` modules available and you want to use JSON to store translations, explicitly specify that: `i18n.set('file_format', 'json')` ### Memoization Setting the configuration value `enable_memoization` in the settings dir will load the files from disk the first time they are loaded and then store their content in memory. On the next use the file content will be provided from memory and not loaded from disk, preventing disk access. While this can be useful in some contexts, keep in mind there is no current way of issuing a command to the reloader to re-read the files from disk, so if you are updating your translation file without restarting the interpreter do not use this option. ### Namespaces #### File namespaces In the above example, the translation key is `foo.hi` and not just `hi`. This is because the translation filename format is by default `{namespace}.{locale}.{format}`, so the {namespace} part of the file is used as translation. To remove `{namespace}` from filename format please change the `filename_format` configuration. i18n.set('filename_format', '{locale}.{format}') #### Directory namespaces If your files are in subfolders, the foldernames are also used as namespaces, so for example if your translation root path is `/path/to/translations` and you have the file `/path/to/translations/my/app/name/foo.en.yml`, the translation namespace for the file will be `my.app.name` and the file keys will therefore be accessible from `my.app.name.foo.my_key`. ## Functionalities ### Placeholder You can of course use placeholders in your translations. With the default configuration, the placeholders are used by inserting `%{placeholder_name}` in the ntranslation string. Here is a sample usage. i18n.add_translation('hi', 'Hello %{name} !') i18n.t('hi', name='Bob') # Hello Bob ! ### Pluralization Pluralization is based on Rail i18n module. By passing a `count` variable to your translation, it will be pluralized. The translation value should be a dictionnary with at least the keys `one` and `many`. You can add a `zero` or `few` key when needed, if it is not present `many` will be used instead. Here is a sample usage. i18n.add_translation('mail_number', { 'zero': 'You do not have any mail.', 'one': 'You have a new mail.', 'few': 'You only have %{count} mails.', 'many': 'You have %{count} new mails.' }) i18n.t('mail_number', count=0) # You do not have any mail. i18n.t('mail_number', count=1) # You have a new mail. i18n.t('mail_number', count=3) # You only have 3 new mails. i18n.t('mail_number', count=12) # You have 12 new mails. ### Fallback You can set a fallback which will be used when the key is not found in the default locale. i18n.set('locale', 'jp') i18n.set('fallback', 'en') i18n.add_translation('foo', 'bar', locale='en') i18n.t('foo') # bar ### Skip locale from root Sometimes i18n structure file came from another project or not contains root element with locale eg. `en` name. { "foo": "FooBar" } However we would like to use this i18n .json file in our Python sub-project or micro service as base file for translations. `python-i18n` has special configuration tha is skipping locale eg. `en` root data element from the file. i18n.set('skip_locale_root_data', True)