Skip to main content
Help us improve Python packaging – donate today!

Translation library for Python

Project Description

# python-i18n [![Build Status](https://travis-ci.org/tuvistavie/python-i18n.png?branch=master)](https://travis-ci.org/tuvistavie/python-i18n) [![Coverage Status](https://coveralls.io/repos/tuvistavie/python-i18n/badge.png?branch=master)](https://coveralls.io/r/tuvistavie/python-i18n?branch=master)


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 !

### 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.

#### 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

Release history Release notifications

History Node

0.3.1

This version
History Node

0.3.0

History Node

0.2.1

History Node

0.2.0

History Node

0.1.3

History Node

0.1.2

History Node

0.1.1

History Node

0.1.0

History Node

0.0.2

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python-i18n-0.3.0.tar.gz (7.9 kB) Copy SHA256 hash SHA256 Source None Jun 9, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page